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(57) Abstract: The present invention in various embodiments provides a computerized wagering game method and apparatus that 
features an operating system kernel (201), a system handler application (202) that loads and executes gaming program shared objects 
(203) and features nonvolatile storage (204) that facilitates sharing of information between gaming program objects (203). The 
system handler of some embodiments further provides an API library of functions callable from the gaming program objects (203), 
and facilitates the use of callback functions on change of data stored in nonvolatile storage (204). The nonvolatile storage (204) also 
provides a nonvolatile record of the state of the computerized wagering game, providing protection against loss of the game state due 
to power loss. The system handler application (202) in various embodiments includes a plurality of device handlers (210), providing 
an interface to selected hardware and the ability to monitor hardware-related events. 
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METHOD FOR DEVELOPING GAMING PROGRAMS COMPATIBLE 
WITH A COMPUTERIZED GAMING OPERATING SYSTEM AND 

APPARATUS 

5 NOTICE OF COPENDING APPLICATIONS 

This application is a non-provisional application claiming priority from 
Provisional Patent Application Serial No. 60/318,369 filed September 10, 2001, 
entitled: Method for Developing Gaming Programs Compatible with a Computerized 
Gaming Operating System and Apparatus (Attorney Docket No. PA0616.ap.US). 

10 

BACKGROUND OF THE INVENTION 

1. Field of the Invention 

The present invention relates to wagering games, particularly computer based 
wagering games, computer based wagering games running on an operating system, 
15 and methods for developing games on a standard gaming operating system. 

2. Backffl-ound of the Art 

Games of chance have been enjoyed by people for thousands of years and 
have enjoyed increased and widespread popularity in recent times. As with most 
forms of entertainment, players enjoy playing a wide variety of games and new 

20 games. Playing new games adds to the excitement of "gaming." As is well knovra in 

the art and as used herein, the term "gaming" and "gaming devices" are used to 
indicate that some form of wagering is involved, and that players must make wagers 
of value, whether actual currency or some equivalent of value, e.g., token or credit. 
This is an accepted distinction in the art fi-om the playing of games, which implies the 

25 lack of value depending upon the outcome and in which skill is ordinarily an essential 

part of the game. On the contrary, within the gaming industry, particularly in 
computer based gaming systems, the absence of skill is a jurisdictional requirement in 
the performance of the gaming play. 

One popular gaming system of chance is the slot machine. Conventionally, a 

30 slot machine is configured for a player to wager something of value, e.g., currency, 

house token, established credit or other representation of currency or credit. After the 
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wager has been made, the player activates the slot machine to cause a random event to 
occur. The player wagers that particular random events will occur that will return 
value to the player. A standard device causes a plurality of reels to spin and 
ultimately stop, displaying a random combination of some form of indicia, for 
5 example, numbers or symbols. If this display contains one of a pre-selected number of 

winning symbol combinations, the machine releases money into a payout chute or 
increments a credit meter by the amount won by the player. For example, if a player 
initially wagered two coins of a specific denomination and that player achieved a 
payout, that player may receive the same number or multiples of the wager amount in 

10 coins of the same denomination as wagered. 

There are many different formats for generating the random display of events 
that can occur to determine payouts in wagering devices. The standard or original 
format was the use of three reels with symbols distributed over the face of the reel. 
When the three reels were spun, they would eventually each stop in turn, displaying a 

15 combination of three symbols (e.g., with three reels and the use of a single horizontal 

payout line as a row in the middle of the area where the symbols are displayed). By 
appropriately distributing and varying the symbols on each of the reels, the random 
occurrence of predetermined winning combinations can be provided in 
mathematically predetermined probabilities. By clearly providing for specific 

20 probabilities for each of the pre-selected winning outcomes, precise odds that would 

control the amount of the payout for any particular combination and the percentage 
return on wagers for the house could be reasonably controlled. 

Other formats of gaming apparatus that have developed in a progression from 
the pure slot machine with three reels have dramatically increased with the 

25 development of video gaming apparatus. Rather than have only mechanical elements 

such as wheels or reels that turn and stop to randomly display symbols, video gaming 
apparatus and the rapidly increasing sophistication in hardware and software have 
enabled an explosion of new and exciting gaming apparatus. The earlier video 
apparatus merely imitated or simulated the mechanical slot games in the belief that 

30 players would want to play only the same games. Early video gaming systems 

therefore were simulated slot machines. The use of video gaming apparatus to play 
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new gaming applications such as draw poker and Keno broke the ground for the 
realization that there were many untapped formats for gaming apparatus. Now 
casinos may have hundreds of different types of gaming apparatus with an equal 
number of significant differences in play. The apparatus may vary from traditional 
5 three reel slot machines with a single payout line, video simulations of three reel 

video slot machines, to five reel, five column simulated slot machines with a choice of 
twenty or more distinct pay lines, including randomly placed lines, scatter pays, or 
single image payouts. In addition to the variation in formats for the play of gaming 
applications, bonus plays, bonus awards, and progressive jackpots have been 

10 introduced with great success. The bonuses may be associated with the play of 

gaming applications that are quite distinct from the play of the original gaming 
format, such as the video display of a horse race with "bets" on the individual horses 
randomly assigned to players that qualify for a bonus, the spinning of a random wheel 
with fixed amounts of a bonus payout on the wheel (or simulation thereof), or 

15 attempting to select a random card that is of higher value than a card exposed on 

behalf of a virtual "dealer." 

Examples of such gaming apparatus with a distinct bonus feature includes 
U.S. Patent Nos. 5,823,874; 5,848,932; 5,836,041; U.K. Patent Nos. 2 201 821 A; 2 
202 984 A; and 2 072 395A; and German Patent DE 40 14 477 Al. Each of these 

20 patents differs in fairly subtle ways as to the manner in which the bonus round is 

played. British Patent 2 201 821 A and DE 37 00 861 Al describe a gaming 
apparatus in which after a winning outcome is first achieved in a reel-type gaming 
segment, a second segment is engaged to determine the amount of money or extra 
games awarded. The second segment gaming play involves a spinning wheel with 

25 awards listed thereon (e.g., the number of coins or number of extra plays) and a 

spinning arrow that will point to segments of the wheel with the values of the awards 
thereon. A player will press a stop button and the arrow will point to one of the 
values. The specification indicates both that there is a level of skill possibly involved 
in the stopping of the wheel and the arrow(s), and also that an associated computer 

30 operates the random selection of the rotatable numbers and determines the results in 
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the additional winning game, which indicates some level of random selection in the 
second gaming segment. 

U.S. Patents Nos. 5,823,874 and 5,848,932 describe a gaming device 
comprising: 

5 a first, standard gaming unit for displaying a randomly selected combination of 

indicia, said displayed indicia selected from the group consisting of reels, indicia of 
reels, indicia of playing cards, and combinations thereof; means for generating at least 
one signal corresponding to at least one select display of indicia by said first, standard 
gaming unit; means for providing at least one discernible indicia of a mechanical 

10 bonus indicator, said discernible indicia indicating at least one of a plurality of 

possible bonuses, wherein said providing means is operatively connected to said first, 
standard gaming unit and becomes actuatable in response to said signal. In effect, the 
second gaming event simulates a mechanical bonus uidicator such as a roulette wheel 
or wheel with a pointing element. 

15 A video terminal is another form of gaming device. Video terminals operate 

in the same manner as a conventional slot and video machine, except that a 
redemption ticket rather than an immediate payout is dispensed. The processor may 
be present in the terminal or in a central computer. 

The vast array of electronic video gaming apparatus that is commercially 

20 available is not standardized within the industry or necessarily even within the 

commercial line of apparatus available from a single manufacturer. One of the reasons 
for this lack of uniformity or standardization is the fact that the operating systems that 
have been used to date in the industry are primitive. As a result, the programmer must 
often create code for each and every fimction performed by each individual apparatus. 

25 Attempts have been made to create a universal gaming engine for a gaming 

machine and are described in Carlson U.S. Patent 5,707,286. This patent describes a 
universal gaming engine that segregates the random number generator and transform 
algorithms so that this code need not be rewritten or retested with each new game 
application. All code that is used to generate a particular game is contained in a rule 

30 EPROM in the rules library. Although the step of segregating random number 
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generator code and transform algorithms has reduced the development time of new 
games, further improvements were needed. 

One significant economic disadvantageous feature with commercial video 
wagering gaming units that maintains an artificially high price for the systems in the 
5 market is the use of unique hardware interfaces in the various manufactured video 

gaming systems. The different hardware, the different access codes, the different pin 
couplings, the different harnesses for coupling of pins, the different functions 
provided from the various pins, and the other various and different configurations 
within the systems has prevented any standard from developing within the technical 

10 field. This is advantageous to the equipment manufacturer, because the gaming 

formats for each system are provided exclusively by a single manufacturer, and the 
entire systems can be readily rendered obsolete, so that the metrket will have to 
purchase a complete unit rather than merely replacement software, and aftermeirket 
gaming designers cannot easily provide a single gaming application that can be played 

15 on different hardware. 

The invention of computerized gaming systems that include a common or 
"universal" video wagering game controller that can be installed in a broad range of 
video gaming apparatus without substantial modification to the gaming apparatus 
controller has made possible the standardization of many components and of 

20 corresponding gaming software within gaming systems. Such systems desirably will 

have functions and features that are specifically tailored to the unique demands of 
supporting a variety of gaming applications and gaming apparatus types, and doing so 
in a manner that is efficient, secure, and cost-effective to operate. 

What is desired is an architecture and method of providing a gaming-specific 

25 platform that features reduced game development time and efficient gaming 

operation, provides security for the electronic gaming system, and does so in a 
manner that is cost-effective for gaming software developers, gaming apparatus 
manufacturers, and gaming apparatus users. An additional advantage is that the use 
of the platform will speed the review and approval process for gaming applications 

30 with the various gaming agencies, bringmg the gaming formats and gaming 
applications to market sooner. 
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The nature of gaming systems and the stringent controls applied to gaming 
systems and gaming applications by jurisdictional controls (e.g., the Nevada State 
Gaming Commission, the New Jersey State Gaming Commission, the Mississippi 
State Gaming Commission, the California State Gaming Commission, the United 
5 Kingdom Gaming Commission, etc.) makes the development of a standard operating 

system and the ability of the game developers to work with such gaming operating 
systems unique within the field of computer based designer/developer interactions. 

One of the reasons that Microsoft Windows® became the leading operating 
system throughout the world for personal computers was based upon its business 

10 strategy of providing access to Microsoft Windows® on-line to developers using an 

Application Program Interface (API) through which developers could communicate 
with the Windows® operating system, without being able to modify the underlying 
operating system (OS). This enabled Windows® to be supported by a vast network of 
private developers so that significant amounts of software became available for 

15 Windows® while other competing operating systems (e.g., Mac OS, Unbc and Linux) 

had much fewer numbers of software programs available to use with these systems. 
However, the Microsoft Windows® operating system was not designed to support 
gaming systems and does not contain the essential software components needed for a 
gaming jurisdiction approvable operating system or gaming application. 

20 Some game systems (as opposed to gaming systems) also attempted an on-line 

approach to assisting developers in using proprietary game operatmg systems for 
development of games compatible with the game operating system. One such on-line 
system was Adventurebuilder, which has apparently been removed firom active on- 
line operation, even though its API addressable OS has been archived at 

25 http://archive.waistl.edu.languages/smalltalk/Smalltalk/st80_CastleMS-. . ./CastleMS.s 

and the entire 195 pages of text can be accessed at that site. 

Additionally, U.S. Patent No. 6,181,336 Bl (Chiu et al.) describes a system 
for providing an integrated, efficient and consistent production environment for the 
shared development of multimedia productions. Examples of multimedia productions 

30 include feature animation films, computerized animation films, interactive video 

games, interactive movies, and other types of entertainment and/or educational 
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multimedia works. The development of such multimedia products typically involves 
heterogeneous and diverse forms of multimedia data. Further, the production tools 
and equipment that are used to create and edit such diverse multimedia data are in and 
of themselves diverse and often incompatible with each other. The incompatibility 
5 between such development tools can be seen in terms of their methods of operation, 

operating environments, and the types and/or formats of data on which they operate. 
The common utilities, methods and services disclosed therein, are used to integrate 
the diverse world of multimedia productions. By using the common utilities, methods 
and services provided, diverse multimedia production tools can access, store, and 
10 share data in a multiple user production environment in a consistent, safe, efficient 

and predictable fashion. 

SUMMARY OF THE INVENTION 

The present invention provides a method for a developer to access a unique 

1 5 gaming operation system that can support a wide variety of gaming applications. The 

developer can access the operating system through an Application Program Interface 
(API), respond to input from the developer without alteration of the gaming 
components stored in the operating system, and then enables the developer, by 
conmiunication with the operating system, to develop a chip, gaming unit or other 

20 software that can be communicationally connected to the operating system to play or 

execute a gaming application, using the operating system as the primary engine for 
running the gamuig application. The developer is capable of using any desired 
software system to develop the gaming application (e.g., Windows® 98, Windows® 
NT, Windows® XT, Mac OS, Unix, Linux, etc.) and still communicate to the gaming 

25 operating system through the API. The developed chip or software stored on one or 

more different media, such as EPROM flash memory, CD ROM, etc. or other 
software containing the gaming play content of a new gaming format may then be 
inserted into any gaming box with the host operating system by simply replacing a 
gaming chip CD ROM, disc or other storage media that has been developed through 

30 use of access to the operating system through the API, and that gaming application is 
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assured of performance and can have a significantly reduced approval time through 
jurisdictional gaming agencies. 

The present invention in various embodiments provides such a method to be 
practiced on a computerized wagering gaming operating system and apparatus that 
5 features a proprietary operating system, such as, for a preferred example, an operating 

system kernel. The apparatus also may include selected device handlers and system 
libraries, and have other device handlers that are disabled or removed. The present 
invention features a system handler application that may be part of the operating 
system. The system handler loads and executes gaming program objects that are part 

10 of the operating system and features nonvolatile storage that facilitates sharing of 

information between gaming program objects. The system handler of some 
embodiments further provides an API library of functions callable from the gaming 
program shared objects, and may in some embodiments facilitate the use of callback 
functions on change of data stored in nonvolatile storage. A nonvolatile record of the 

15 state of the computerized wagering gaming application is stored on the nonvolatile 

storage, providing protection against loss of the gaming state due to power loss. The 
system handler application in various embodiments includes a plurality of device 
handlers, providing an interface to selected hardware and the ability to monitor 
hardware-related events, 

20 

BRIEF DESCRIPTION OF THE DRAWINGS 

Figure 1 shows a computerized wagering game apparatus as may be used to 
practice an embodiment of the present invention. 

Figure 2 shows a more detailed structure of program code executed on a 
25 computerized wagering game apparatus, consistent with an embodiment of the present 

invention. 

Figure 3 is a diagram illustrating another exemplary embodiment of a 
universal gaming system according to the present invention having a universal or 
open operating system. 
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Figure 4 is a diagram illustrating one exemplary embodiment of a method of 
converting a gaming system to a gaming system having an open operating system 
according to the present invention. 

Figure 5 is a diagram illustrating one exemplary embodiment of a set of 
5 devices used for interfacing with a device driver or handler in an open operating 

system in a gaming system according to the present invention. 

Figure 6 is a diagram illustrating one exemplary embodiment of a resource 
manager used in a gaming system according to the present invention. 

Figure 7 is a diagram of a table illustrating one exemplary embodiment of a 
10 resource file used in a gaming system according to the present invention. 

Figure 8 is a diagram illustrating one exemplary embodiment of a cashless 
gaming system using the universal gaming system according to the present invention. 

Figure 9 is a diagram illustrating one exemplary embodiment of configuring a 
game usable in a gaming system according to the present invention. 
15 Figure 10 is a diagram illustrating another exemplary embodiment of 

configuring and/or storing a game on a removable media useable in a gaming system 
according to the present invention. 

Figure 11 is a diagram illustrating another exemplary embodiment of a gaming 
system according to the present invention wherein the game layer is programmable or 
20 configurable via a web page at a location remote fi-om the gaming system. 

Figure 12 is a diagram illustrating one exemplary embodiment of a web page 
template used in the gaming system shown in Figure 1 1 . 

Figure 13 is a diagram illustrating one exemplary embodiment of nonvolatile 
memory used in a gaming system according to the present invention, wherein the 
25 nonvolatile memory is configured as a RAID system. 

Figure 14 is a block diagram that shows the operation of API's between 
software components. 

DETAILED DESCRIPTION OF THE INVENTION 

30 In the following detailed description of sample embodiments of the invention, 

reference is made to the accompanying drawings that form a part hereof, and in which 
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is shown by way of illustration specific sample embodiments in which the invention 
may be practiced. These embodiments are described in sufficient detail to enable 
those skilled in the art to practice the invention, and it is to be understood that other 
embodiments may be utilized and that logical, mechanical, electrical, and other 
5 changes may be made without departing from the spirit or scope of the present 

invention. The following detailed description is, therefore, not to be taken in a 
limiting sense, and the scope of the invention is defined only by the appended claims. 
It is essential to an appreciation of the practice of the present invention that the 
jurisdictional approval requirements and the industry standards of the gaming industry 
10 be considered in determination of the skill and technical sophistication of the present 

technology and invention. 

In this document, the term "software component" can refer to any software 
module or grouping of modules. Under this definition a protocol module could be 
15 considered to be a type of software component, as could a complete operating system, 

or even a piece of an operating system. For the purposes of this document, a 
"software componenf ' will be considered to be the set of code that an individual 
operating system provider provides. 

20 The Nevada Gaming Control Board defines a gemiing-related software 

component and uses a simple test to determine if a software subsystem falls under the 
definition of a gaming device. A primary element of a "Gaming Device" under NRS 
463.0155 is a component that must be used remotely or directly in connection with a 
game (gaming application) and that affects the result of a wager by determining win 

25 or loss (based on a probability). Taking into account this definition, the Nevada 

Gaming Control Board uses a simple test: if an operating system or other software 
component can be shown to be usable in other fields or applications and the 
component is not involved in the calculation of wagering win or loss, then it is not a 
gaming-related piece of software. Those software components that relate to the 

30 presentation, decision-making and storage of win/loss information are the ones that 

are of primary concern to the Commission. 
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Nevada gaming laws and regulations require that the "Manufacturer" of a 
gaming device must be licensed. Manufacturer is defined in NRS 463.0172 as one 
who: "manufactures, assembles, programs or makes modifications to a gaming device 
5 or cashless wagering system ... or who designs, controls the design or maintains a 

copyright over the design of a program which can't be reasonably demonstrated to 
have any use other than in a gaming device or cashless wagering system." 

Therefore, where a gaming device contains software written by multiple 
10 vendors, an analysis must be made as to whether a gaming license is required by each 

vendor depending on whether the component provided by each vendor is gaming 
related. It may be that a vendor that supplies certain code may not have to be licensed 
in order for a licensed vendor to include that code on a gaming device. The 
complications arise when considering the different possibilities that can occur, as 
1 5 considered below. 

The concept of trust or authenticity is the basis of all gaming regulations. To 
have a high degree of confidence in the fairness, integrity and security of a gaming 
device, it is necessary to be able to trust that the software components really do what 

20 they have been tested for and approved to do. There are different ways to establish 

such trust. Providing source code and other documentation of the software 
component is one such method. Other methods include public key infirastructure 
(PKI) to authenticate game code and data, requiring that the physical storage location 
for the code be on unwritable media, etc. In the case of PKI authentication, it is 

25 critical that the software component that provides the authentication sei-vice has the 

highest level of trust. If this is not true, then the purpose is entirely lost. For tihie 
purposes of this document, it will help with clarity to refer to the software component 
that provides authentication services as the operating system, or just OS. This is 
mainly for readability and understanding, but it is important that in systems that 

30 contain multiple software components, an OS/application type-relationship between 

the components is just one configuration. 
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Most gaming jurisdictions require devices that contain code that is stored in 
writable media to have an approved method to verify the integrity of the code that is 
stored there. Using PKI signatures is a commonly used and accepted method for such 
5 authentication. This implies that one softv^are component inherently has a higher 

trust level than the one being authenticated. In gaming jurisdictions, read-only 
storage on EPROM with available source code has the highest level of trust because 
the code can be easily verified by spot-checking devices in the field. The code that 
exists on the EPROM will in turn check the signatures for the code stored on the 

10 writable media. Assuming things check out, the device may now proceed with 

operation. U.S. Patent Nos. 6,149,552; 6,106,396; 6,104,859; and 5,643,086 (The 
Alcorn Patents) describe various authentication techniques for use in gaming systems. 
Although authentication and/or encryption systems are essential for commercial 
computer based gaming products, they need not be present on the system that is 

15 provided for access to the developer. The absence of the authentication system at this 

point in the development procedure may simplify communication and additionally 
speed up development. The authentication system and the encryption processes 
attendant thereto may be added into the commercial gaming apparatus without 
adversely affecting the ability of the developed gaming application or gaming rules 

20 chip to operate on the operating system. 

The availability of source code mentioned above is extremely important when 
one considers this hierarchy of trust between software components that has to be 
strictly enforced in order to not compromise the integrity of the system. Only those 

25 software components that have the highest level of trust should be in a position to 

certify or authenticate other components. Those components that exist on writable 
media or do not have source code availability automatically have a lower level of 
trust. In the case of unlicensed vendors of operating systems with no source code 
available, for example, you have a situation where an untrusted, unproven software 

30 . component provides authentication to a component on writable media, which is 
questionable at best. That provides a complication in the development of gaming 



12 



wo 03/023647 



PCT/US02/30286 



application software and hardware to be used on a proprietary operating system, 
particularly on-line (over the internet) where identification of users may be 
problematic and control over secondary distribution or redistribution of the operating 
system and its source codes are problematic. Such uncontrolled distribution could 
5 compromise the ultimate security of the gaming apparatus in the casinos, and could 

lead to a refusal of gaming operators for the proprietary gaming operating system and 
for gaming applications provided on that operating system. 

As indicated above, an API, or Application Programming Interface, is a set of 
10 methods used to interface from one communicator (e.g., a developer operating on its 

own computer and operating system) to a distal information component such as a 
software component (distal meaning over the internet, on-line, off a memory source 
such as compact disk, floppy disk, connected hard drive, or other information storage 
media with which the developer can communicate). These methods may be 
15 implemented using message passing, function calls using static or dynamic linking, or 

some other way. The important common fiinction of every API is to isolate the data 
and low-level fimctions in one software component from being accessed except 
through the use of a common set of access methods. 

20 The primary problem with having a number of software components existing 

on a single system has to do with defining the boundaries between the components. 
The only way the components can be separated into completely contained pieces is to 
define an API to which all the components conform. As long as this is the only way 
in which the pieces interact, the security of the distal information component is 

25 satisfactory. 

One way of overcoming the delays and difficulties in introducing gaming 
applications to the industry is by practicing a method within the scope of the present 
invention. As a first step, a gaming operating system is provided that contains objects 
30 that can be used in gaming applications and gaming apparatus (whether video gaming 

or reel-type gaming apparatus). This gaming operating system would include 
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functions in a secure computing system (e.g., computer, server, microprocessor, etc.) 
or memory system (floppy disk, compact disk, optical disk, hard drive, etc.), these 
functions being useful in gaming apparatus. The developer provides gaming 
application specific data (that is rules, directions, payout schedules, numbers of 
5 rounds, player activity requirements, and the like) to the Application Programming 

Interface, creates and ultimately compiles the information needed to direct the gaming 
operating system to execute the functions necessary to play the gaming application, 
and provide that compiled information to a gaming apparatus with the operating 
system in a commercial environment to practice the game. 

10 

The method comprises assisting in the development of a computer based 
wagering gaming application with at least the steps of: 

providing a gaming operating system comprising a library of at least two 
software gaming callback functions and/or primary gaming states; 
15 providing an Application Programming Interface enabling communication 

from a distal intelligence source to the gaming operating system; 

communicating with the Application Programming Interface to the functions 
and/or primary gaming states in the library of the gaming operations; 

providing gaming specific data relating to at least one specific gaming 
20 application; and 

compiling a program specific to at least one gaming application that is 
compatible with the gaming operating system through the use of the gaming operating 
system API. 

25 This method could have the compiled program specific to at least one gaming 

application provided on a storage device. Some gaming applications have multiple 
games, and/or bonus rounds that can be included on the storage device. The method 
may be practiced either with or without security features enabled when 
communicating with the Application Programming Interface is performed. Security 

30 features can be added later when the commercial product is introduced or qualified by 

the regulatory commissions. 
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Another way of describing the method would be as assisting in the 
development of a computer based wagering gaming application comprising the steps 
of: 

5 providing a gaming operating system comprising a library of at least two 

software gaming elements selected from the group consisting of a random number 
generator, a game initiation sequence, a value module (e.g., one or more modules 
providing controls relating to coin changing, coin recognition, currency recognition, 
credit recognition/storage, ticket recognition/printout, etc.), a bonus module (e.g., 

10 bonus, jackpot, additional play, alternative play), a video gaming module (e.g., 

including actual image files, image sequencing files, clip art files, video storage files 
[e.g., empty or partial files], color files, etc.), an audio gaming module (sound files, 
sound sequence files, sound files tied to video events, volume controls, etc.), a jackpot 
module, a graphics conversion tool, a debugging tool, a pay-out table module, a 

15 value-handling module, a power-loss back-up module, a gaming payout history 

module, a player history module, and a user interaction module (e.g., handle controls, 
button controls, touch-screen controls, joystick controls, etc.); 

providing an Application Programming Interface enabling communication 
fi-om a distal intelligence source to the gaming operating system; 

20 communicating with the Application Programming Interface to functions 

and/or primary gaming states in the library of the gaming operating system; and 

compiling a program specific to at least one gaming application that is 
compatible with the gaming operating system. 

The method may affect compiling of the program including writing a program 

25 that comprises gaming application specific commands that communicate with the 

gaming operating system. The method may be practiced in conjunction with a user 
manual with directions on accessing files in the library and is used by using specific 
commands in the user manual to access specific files or functions in the operating 
system through the Application Programming Interface. 
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For those software components which use PKI (pubUc key infrastructure) for 
authentication of other components in the system, it is desirable to create a new pair 
of public/private keys for each software release. There are several reasons for this: 

• Matching software releases by version 

5 • Simplification of the regulatory approval process 

• Barrier to brute-force cracking techniques 

• Preventative security measures 

• Jurisdictional non-compatibility 

"Revving" is the process by which public or private keys are replaced in the OS 
10 ROM. Private keys are used to generate signatures and the public key is used to verify 

the signatures. This ordinarily is done every time that a new version of software is 
introduced into new gaming jurisdictions or even the same gaming applications to 
different jurisdictions. 

15 In the software development process, small inconsistencies and 

incompatibilities will creep into an API as new features are added and changes are 
made to the internal workings of a software component. This is true especially in an 
embedded environment where it is not cost effective or space effective to have 
multiple sections of redundant code. One way to ensure that the devices in the field 

20 are using compatible software components is to somehow prevent incompatible 

versions fi-om co-existing. Revving the public/private key pairs with each release of 
a trusted software component is one such method. 

One significant delay in the introduction of gaming applications to the market 
has involved the complexity and length of regulatory approval. For example, 

25 consider a circumstance where there are hundreds of games deployed with a certain 

OS. Each of these games runs on a certain version of the software (most likely the 
latest version) but not necessarily so. When a new version of that OS is released, 
gaming regulations require that approval is obtained for all possible game 
configurations which exist in the field. This means that if every version of OS uses 

30 the same keys, it would be necessary to test and submit for approval every old game 
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that existed in the field with old versions, because there would be no mechanism 
preventing someone from using an old version with new game code. 

With a different key pair for every OS version, only new games would ever 
5 have to be submitted for approval, since the old games would automatically not work 

with the new keys and consequently, the new operating system. 

If someone wanted to discover a private key and did not have a mathematical 
way of doing so (for the encryption technique described above, there are no such 

10 known methods) they would try to discover the key by guessing. This may be hard to 

do with a key length of 5 12 bits, but someone with a lot of computer power might 
eventually be able to guess the correct key. By using very long keys, this approach 
has been made as impractical as possible. For this reason, the more impractical it is to 
guess keys the better, as far as security of keys is concerned. Therefore, if new keys 

15 are generated every time a version of software is released, it will be that much more 

impractical for someone to try to guess the keys. This makes the overall system more 
secure. 



One of the most important aspects to consider with the PKI method of using 
20 signatures for the verification of gaming chips is that regulatory agencies base their 

approval on the confidence that exists in maintaining the secrecy of the private key. 
Since anyone who might want to cheat the gaming application must modify the game 
code, if they do not know the private key, they will be unable to generate signatures 
for the gaming application to work. If a private key is lost, the integrity of every 
25 machine in the field which uses that public/private key set is compromised. The only 

way to correct this compromise in security is to generate a new public/private key pair 
and upgrade every machine with the new public key. If the same set of keys has been 
used for every software release, this means the manufacturer must generate a new 
public/private key pair and upgrade every version of OS in the field. With a different 
30 public/private key set for each OS version, only a subset of machines in the field will 
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have to be upgraded if a key is compromised, which translates to less cost and less 
disruption to the casino's business. 

Another important issue to consider is the fact that some manufacturers may 
5 use the same software component in several different jurisdictions. It is desirable to 

ensure that a gaming application written for one jurisdiction will not operate in a 
machine in a different jurisdiction. Also, vendors that are licensed in one jurisdiction 
should not have the keys to produce gaming applications for another jurisdiction. It 
will be desirable, therefore, to have different sets of keys for different gaming 
10 jurisdictions as well as for each software release. 

When software components that exist on a system are the properly of different 
vendors, complications arise in the case where one piece is found to have a serious 
security hole or other bug that causes the regulatory agency to have to disapprove the 
15 software. When any software component on a gaming device is disapproved, the 

gaming device as a whole will be disapproved. There are several issues with this set 
of circumstances, including at least liability, procedures and unlicensed vendor 
complications. 

20 The timing of re-submission versus deadlines to remove the disapproved 

software fi-om the field causes a potential liability issue when a bug fix cannot be 
found quickly enough. There should most likely be procedures that vendors should 
follow for tracking software installation and revisions in the field. Without such 
procedures, it would be impossible to do a coordinated software upgrade if the need 

25 arises. 

If more than one software component interacts with a third component through 
the same API, there can be side effects known as couplings. For example, if a 
software function enables or disables a software feature, then an outside module could 
30 call the function to turn the feature on and a second module may then turn the feature 
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off. Unless the two modules are communicating with each other, there will be 
problems with the two modules existing on the same system. 

In systems where there is an OS / application relationship between software 
5 components, there can be a time coupling between all API calls, especially if there is 

an ability to preemptively multitask the application processes in the system. Because 
the multitasking can happen at any time, the order in which API calls can happen may 
change from run to run. This means that the application code needs a layer of error 
checking to prevent race condition bugs that would otherwise be unnecessary. For 
10 this reason, having a single thread of execution for which the order that API calls are 
made is always the same will automatically have a greater level of trust than will a 
multitasking OS. This is not to say that a multitasking OS cannot overcome this 
deficiency by correctly using mutexes, but this obviously is more complicated to test 
and therefore is harder to trust and obtain approval. 

15 

There can also exist couplings between API calls. These couplings are 
different from the interaction couplings pointed out earlier. These couplings are 
inherent in the way the API operates. The classic example of this type of coupling is 
the following API for a voltmeter: 

20 Set_range(voIts) 

Set_sensitivity(volts_per_division) 
The underlying parameters that are being controlled by both of these API calls are the 
minimum and maximum voltages that will be sensed by the voltmeter. However, at 
high voltage range settings, certain sensitivities may be unavailable due to the way the 

25 voltmeter senses voltages. This illustrates a functional coupling in an API. The 

generic way to describe these couplings is that one API call can affect the available 
settings or range of settings that are available to another API call. 

One method of verifyuig software components is to define a series of 
30 regression tests and expected test results for the individual pieces. This method is 
useful for identifying programming errors and bounds checking problems with the 
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API implementation, but is less useful in identifying system-level weaknesses which 
my be inherent in the design. 

A front-end code verifier or pre-parser may be written that allows developer 
5 code to be scanned before compiling to identify errors in the code as it relates to the 

gaming operating system API. This type of scanner can be used to find couplings and 
other errors that a regression tester may not find. 

In the past, vendor collaboration by defining a standard API specification in 
10 the gaming industry has been difficult and unsuccessful. A good example of this is 
the various protocol implementations that exist which are not always 100% 
compatible. With software components co-existing on the same machine, there can be 
no way around the fact that if something is not 100% compatible with the API 
specifications, there could easily be bugs introduced which would compromise the 
15 integrity of the device, which is clearly unacceptable in any jurisdiction. 

For purposes of this disclosure, the following terms have specialized meaning, 
and are defined below: 

"Memory" for purposes of this disclosure is defined as any type of media 
20 capable of read/write capability. Examples of memory are RAM, tape, flash memory, 

disc on chips and floppy disc. 

"Shared or Game Program Objects" for purposes of this disclosure are defined 
as self-contained, functional units of game code that define a particular feature set or 
sequence of operation for a game. The personality and behavior of a gaming machine 
25 of the present invention are defined by the particular set of shared objects called and 

executed by the operating system. Within a single game, numerous game objects may 
be dynamically loaded and/or executed. 

"Architecture" for purposes of this disclosure is defined as software, hardware 
or both. 

30 "Dynamic Linking" for purposes of this disclosure is defined as linking at run 

time. 
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"API" for purposes of this disclosure is an Application Programming 
Interface. The API includes a library of functions. 

"System Handler" for purposes of this disclosure is defined as a collection of 
code written to control non-gaming specific device handlers. Examples of device 
5 handlers include I/O, sound, video, touch screen, nonvolatile RAM and network 

devices. 

"Gaming Data Variables" for purposes of this disclosure includes at a 
minimum any or all data needed to reconstruct the gaming state in the event of a 
power loss. 

10 

The present invention comprises various elements to enable the use and 
installation of a novel gaming operating system that in turn enables more rapid 
development and deployment of novel gaming games. One element of the invention 
is a computerized wagering game apparatus comprising: 

15 a computerized game controller operable to control the computerized 

wagering game having a processor, memory, and nonvolatile storage; and 

an operating system comprising: a system handler application which 
provides gaming related functions and services to game programs; and 

an operating system kernel that executes the system handler 

20 application. The computerized wagering game apparatus may have the system handler 

application comprise at least one system selected from the group consisting of a) a 
plurality of device handlers, b) software having the ability when executed to: 

load a gaming program and execute the new gaming program; c) an API with 
functions callable from the game program; d) an event queue; e) a game personality 

25 described in a selected mode; and f) a combination of an event queue that determines 

the order of execution of each specified device handler; an API having a library of 
functions; an event queue capable of queuing on a first come, first serve basis; and an 
event queue capable of queuing using more than one criteria. The computerized 
wagering game apparatus may have game data modified by gaming program objects 

30 that are stored in nonvolatile storage or wherein the system handler and kernel work 

in communication to hash system handler code and operating system kernel code. By 
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way of non-limiting examples, the game data modified by gaming program objects 
may be stored in nonvolatile storage and changing game data in nonvolatile storage 
causes execution of a corresponding callback function in the system handler 
application. The computerized wagering game apparatus may have the operating 
5 system kernel as a Linux operating system kernel having customized proprietary 

modules and the kernel has at least one modification wherein each modification is 
selected from the group consisting of: 1) accessing user level code from ROM, 2) 
executing from ROM, 3) zeroing out unused RAM, 4) testing and/or hashing the 
kernel, and 5) disabling selected device handlers. The computerized wagering game 

10 apparatus may have the apparatus contain a machine-readable element with machine- 

readable instructions thereon, the instructions when executed operable to cause the 
processor to manage at least one gaming program object via a system handler 
application and to execute a single gaming program object at any one time, wherein 
gaming program objects are operable to share game data in nonvolatile storage within 

15 the processor in the computerized wagering game system. 

The computerized wagering game apparatus may have programming direct the 
gaming apparatus to effect a procedure selected from the group consisting of a) only 
one gaming program object executes at any one time, b) there are instructions 
20 operable when executed to cause a computer to provide functions through an API that 

comprises a part of the system handler application, and c) when instructions are 
executed, the instructions are operable to store game data in nonvolatile storage, such 
that the state of the computerized wagering game system is maintained when the 
machine loses power. 

25 

A method of assisting in the development of a computer based wagering 
gaming application can utilize any of the apparatus described herein by the steps of: 

providing a gaming operating system comprising a library of at least two 
software gaming callback functions and/or primary gaming states; 
30 providing an Application Programming Interface enabling communication 

from a distal intelligence source to the gaming operating system; 
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communicating with the Application Programming Interface to the functions 
and/or primary gaming states in the library of the gaming operating system by 
providing a Makefile or other procedure for building a gaming application, and a 
configuration file for running the gaming operation system on a proximal computing 
5 system; 

providing gaming specific data relating to at least one specific gaming 
application; and 

compiling a program specific to at least one gaming application that is 
compatible with the gaming operating system. 

10 This method of assisting in the development of a computer based wagering gaming 

application may also comprise using a library of at least two software gaming 
elements comprising gaming elements selected fi-om the group consisting of random 
number generator, game initiation sequence, bonus module, video gaming module, 
audio gaming module, jackpot module, graphics conversion tool, debugging tool, pay- 

15 out table module, value-handling module, power-loss recovery module, gaming 

payout history module, player history module, and user interaction module. Also, the 
process may have public and/or private authentication keys revved and different 
public and/or private authentication keys are provided to each of at least two different 
legal jurisdictions. 

20 

A method of managing data in a computerized wagering game apparatus as 
described herein can be practiced via a system handler application in a method of 
loading a shared object, executing the shared object, and accessing and storing game 
data in nonvolatile storage. This method may have further steps of a) unloading the 
25 first program object, and loading a second program object or b) executing a 

corresponding callback function upon alteration of game data in nonvolatile storage. 

The present invention also includes a machine-readable memory storage 
element with instructions thereon, the instructions when executed operable to cause a 
30 computer to: load a first program shared object, execute a first program shared object, 

store gaming data in nonvolatile storage, such that a second program object later 
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loaded can access gaming data variables in nonvolatile storage, unload the first 
program shared object from system memory, and load the second program shared 
object to system memory so that the second program shared object is accessible to the 
computer as instructions. This machine-readable memory storage element may have 
5 additional instructions operable when executed to cause a computer to perform a task 

selected from the group consisting of a) executing a corresponding callback function 
upon alteration of game data in the nonvolatile storage; and b) managing events via 
the system handler application. 

10 Another aspect of the present invention includes a universal operating system 

stored in a memory storage component that may be operatively inserted along with 
game identity data into an electronic or electromechanical gaming device having 
ancillary functions so that the gaming device can effect play of the game provided in 
the game identity data. The operating system will control at least one ancillary 

15 function selected from the group consisting of coin acceptance, credit acceptance, 

currency acceptance and boot up, the gaming device having at least one system 
handler application, and the operating system comprising a system handler and an 
operating system kernel. This operating system may also have at least one of a 
plurality of APIs, an operating system kernel customized for gaming purposes, and an 

20 event queue, or a system handler having a plurality of device handlers or the operating 

system controls a networked on-line system or control a progressive meter. The 
operating system may also have a kernel customized for gaming purposes utilizing a 
method of operation selected from the group consisting of: 1) accessing user level 
code from ROM, 2) executing from ROM, 3) zero out unused RAM, 4) test and/or 

25 hash the kernel, and 5) disabling selected device handlers. 

Another method within the scope of the invention can be generally described 
as a) customizing an operating system kernel and b) providing the customized kernel 
of the operating system into a gaming apparatus, at least one customization being 
30 effected to obtain functionality of the gaming apparatus, the customization being a 

kernel modification for a process selected from the group consisting of: 
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1) accessing user level code from ROM; 

2) executing user level code from ROM; 

3) zeroing out unused RAM; 

4) testing and/or hashing the kernel; and 

5) disabling selected device handlers. 



on 



in 



Another method within the scope of the invention can be generally described 
as converting a first game that operates on a first gaming system so that the game 
operates on a universal gaming system, the method comprising: removing a first game 

10 operating system from the gaming system, the first game operating system including 

hardware and software; installing the universal gaming system in place of the game 
operating system, the universal gaming system including a game program layer, an 
open operating system, and a game controller for running the game program layer 
the open operating system; providing functional interfaces between the universal 

15 gaming system and game devices; and installing a second game specific program i 

the game program layer configured to operate with the open operating system. This 
method may have at least one step selected from the group consisting of: 

a) providing the open operating system with a system application 
handler, wherein the functional interfaces include a functional interface between the 

20 gammg system and the game devices via the system application handler; 

b) configuring the system handler application to include one or more 
device handlers for interfacing with the game devices, wherein at least one of the 
device handlers operates as a protocol manager between the games device and the 
open operating system; 

25 c) providing the open operating system to include an operating system 

kernel that executes the system handler application; and 

d) providing the game program layer with at least one gaming program 

object. 

This method may have the at least one gaming program object specific to a type of 
30 game played on the universal gaming system. The method may also have at least one 

step selected from the group consisting of : 
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changing a type of game played on the universal gaming system by 
changing game program objects; 

configuring the game program layer to operate the game as a slot 

machine; 

5 operating the slot machine as a mechanical reel-based slot machine; 

and 

configuring the open operating system to include a resource manager 
for mapping game specific resources. 
This method may include mapping game specific resources by parsing a configuration 

10 file, mapping operating system resources based on the configuration file, and storing 

the resource map in memory. This mapping of the operating system resources may be 
based on the configuration file includes mapping input/output lines to system 
resources. The method may enable converting the first gaming system from a 
cash accepting gaming system to a cashless gaming system, the method including 

15 providing the open operating system with a system application handler, wherein the 

fimctional interfaces include a fimctional interface between the gaming system and 
the game devices accomplished via the system application handler, and configuring 
the system handler application to include one or more device handlers for interfacing 
with the game devices, the configuring including installing a card reader device 

20 handler, and installing a card reader in communication with the card reader device 

handler, and optionally including configuring the system handler application to 
include a ticket printer device handler; and installing a ticket printer in 
communication with the ticket printer device handler. This method may be practiced, 
by way of a non-limiting example on a slot machine game operating system that is 

25 removed from the first gaming system and where the functional interfaces are 

between the universal gaming system and slot machine game devices. This method 
may also perform at least one step selected from the group consisting of: a) providing 
the open operating system with a system application handler, wherein the fimctional 
interfaces include a functional interface between the gaming system and the slot 

30 machine game devices via the system application handler; b) configuring the system 

handler application to include one or more device handlers for interfacing with the 
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Slot machine game devices, wherein at least one of the device handlers operates as a 
protocol manager between the slot machine games device and the open operating 
system; c) configuring an I/O device handler to interface with slot machine input 
devices and slot machine output devices; d) providing slot machine input devices that 
5 include a mechanical arm, button acceptor and coin acceptor; and e) providing the slot 

machine with output devices inclusive of slot machine reels, credit displays, and 
speakers. The method may act to convert the mechanical reel slot machine game 
having only cash, token, credit balance and currency acceptance capability to a 
cashless gaming system via the system handler application, the converting includmg 
1 0 providing a card reader device handler, and installing a card reader in communication 

with the card reader device handler and optionally providing a ticket printer device 
handler, and installmg a ticket printer in communication with the ticket prmter device 
handler. 

1 5 Another aspect of the method of the present invention is a method of 

configuring a game program layer for a universal gaming system that is configured 
for a game program layer and an open operating system, the method comprising: 
configuring the game program layer on a computer remote fi-om a first non-universal 
gaming system; and downloadmg the game program layer into the universal gaming 

20 system and performing at least one sequence comprising: 

a) defining a game template; and configuring the game program 
layer using the game template; 

b) storing the game program on a removable media card; and 

c) providing removable media as flash memory. 

25 This method may be practiced, for example, where the game program is stored on a 

removable media card and the removable media card is plugged into the gaming 
system, and then running the game program layer via the open operating system fi-om 
the removable media card. This method may also have an additional step of preparing 
the game program layer for authentication by plugging the removable media card into 

30 an authenticatmg system. This method may be performed, in a non-limiting example, 

as a network based method of providing a game program layer for a universal gammg 
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system configured for remote operation using an open operating system, the method 
including defining a user interface to communicate between the remote computer and 
the universal operating system. For example, the game program layer is configured to 
use user interface remote from the gaming system or via a web page template at the 
5 user interface. 

The present invention may also comprise a gaming system suitable for use in a 
casino comprising: a game controller configured to operate the gaming system; and a 
first nonvolatile memory and a second nonvolatile memory for storing critical gaming 
10 information, wherein the first nonvolatile memory and the second nonvolatile 

memory are configured to communicate with the game controller as a gaming RAID 
system for redundant storage of critical gaming information. RAID not defined in 
text, the gaming system enabling redundant NVRAM storage to be replaceable while 
operating power for the system is on. 

15 

The present invention includes a method of accessing a computerized gaming 
operating system by a method and apparatus. The operating system has novel 
gaming-specific features that improve security, make development of game code 
more efficient, and do so using an apparatus and software methods that are cost- 

20 effective and efficient. The present invention also reduces the amount of effort 

required to evaluate and review new game designs by gaming regulators, because the 
amount of code to be reviewed for each game is reduced by at least as much as 40%, 
preferably at least 50%, more preferably at least 60% or even at least 70%, and as 
much as 80% or more over known, machine-specific architecture that one skilled in 

25 the art might wish to insert into gaming systems. That is, in the practice of the present 

invention, rather than having every line of code or software screened, certain software 
is essentially *pre-approved' by previous inspection and only game code additions 
(and the like) need to be reviewed for approval. The invention provides, in various 
embodiments, features such as a nonvolatile memory for storing gaming application 

30 variables and game state information, provides a shared object architecture that allows 

individual game objects to be loaded and to call common functions provided by a 
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system handler application, and in one embodiment provides a custom operating 
system kernel that has selected device handlers disabled. 

Incorporated by reference in this description is the Shuffle Master Gaming, 
5 Game Operating System "SGOS" Developer's Manual, revised May 2001 comprising 

175 pages that are attached hereto and incorporated herein as part of this specification. 
This Developer's Manual has not been published, but has been provided under limited 
access under confidentiality agreements with potential developers, and does not 
constitute prior art. No commercial products have been introduced using this manual 
10 or the development procedures and systems of die present invention as of 1 0 

September 2001. 

Figure 1 shows an exemplary gaming system 100, illustrating a variety of 
components typically found in gaming systems and how they may be used in 

15 accordance with the present invention. User interface devices in this gaming system 

include push buttons 101, joystick 102, and pull arm 103. Credit for wagering may be 
established via coin or token slot 104, a device 105 such as a bill receiver or card 
reader, or any other credit input device. A card reader 105 may also provide the 
ability to record credit information on a user's card when the user has completed 

20 gaming, or credit may be returned via a coin tray 106 or other credit return device. 

Information is provided to the user by devices such as video screen 107, which may 
be a cathode ray tube (CRT), liquid crystal display (LCD) panel, plasma display, 
light-emitting diode (LED) display, mechanical reels or wheels or other display 
device that produces a visual image under control of the computerized game 

25 controller. Also, buttons 101 may be lighted to indicate what buttons may be used to 

provide valid input to the game system at any point in the game. Still other lights or 
other visual indicators may be provided to indicate game information or for other 
purposes such as to attract the attention of prospective game users. Sound is provided 
via speakers 108, and also may be used to indicate game status, to attract prospective 

30 game users, to provide player instructions or for other purposes, under the control of 
the computerized game controller. 
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10 



The gaming system 100 further comprises a computerized game controller 1 1 1 
and I/O interface 1 12, connected via a wiring harness 1 13. The universal game 
controller 1 1 1 need not have its software or hardware designed to conform to the 
interface requirements of various gaming system user interface assemblies, but can be 
designed once and can control various gaming systems via the use of machine- 
specific I/O interfaces 1 12 designed to properly interface an input and/or output of the 
universal computerized game controller to the harness assemblies found within the 
various gaming systems. 



In some embodiments, the universal game controller 1 11 is a standard IBM 
Personal Computer-compatible (PC compatible) computer. Still other embodiments 
of a universal game controller comprise general purpose computer systems such as 
embedded controller boards or modular computer systems. Examples of such 
15 embodiments include a PC compatible computer with a PC/104 bus that is an example 

of a modular computer system that features a compact size and low power 
consumption while retaining PC software and hardware compatibility. The universal 
game controller 1 1 1 provides all functions necessary to implement a wide variety of 
games by loading various program code on the universal controller, thereby providing 
a common platform for game development and delivery to customers for use in a 
variety of gaming systems. Other universal computerized game controllers consistent 
with the present invention may include any general-purpose computers that are 
capable of supporting a variety of gaming system software, such as universal 
controllers optimized for cost effectiveness in gaming applications or that contain 
other special-purpose elements yet retain the ability to load and execute a variety of 
gaming software. Examples of special purpose elements include elements that are 
heat resistant and are designed to operate under less than optimal environments that 
might contain substances such as dust, smoke, heat and moisture. Special purpose 
elements are also more reliable when used 24 hours per day, as is the case witii most 
gaming applications. 
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The computerized game controller of some embodiments of the present 
invention is a computer running an operating system with a gaming application- 
specific kernel. In alternative or further embodiments, a game engine layer of code 
executes within a non-application specific kernel, providing common game 
5 functionality. The gaming program shared object in such embodiments is therefore 

only a fraction of the total code, and relies on the game engine layer and operating 
system kernel to provide a library of gaming functions. A preferred operating system 
kernel is the public domain Linux 2.2 kernel available on the Internet. Still other 
embodiments will have various levels of application code, ranging from embodiments 
10 containing several layers of game-specific code to a single-layer of game software 

running without an operating system or kernel but providing its own computer system 
management capability. 

Figure 2 illustrates the structure of one exemplary embodiment of the 
15 invention, as may be practiced on a computerized gaming system such as that of 

Figure 1 . The invention includes an operating system 300, including an operating 
system kernel 201 and a system handler application 202. An operating system kernel 
201 is first executed, after which a system handler application 202 is loaded and 
executed. The system handler application in some embodiments may load a gaming 
20 program shared object 203, and may initialize the game based on gaming data 

variables stored in nonvolatile storage 204. In some embodiments, the gaming data 
variables are mapped using a Game. State data file 205, which reflects the data stored 
in nonvolatile storage 204. The nonvolatile RAM (NV-RAM) according to the 
invention has read/write capability. The gammg program object in some 
25 embodiments calls separate API functions 206, such as sound functions that enable 

the gaming apparatus to produce sound effects and music. 

The OS kernel 201 in some embodiments may be a Linux kernel, but in 
alternate embodiments may be any other operating system providmg a similar 
30 function. The Linux 2.2 operating system kernel in some further embodiments may 

be modified for adaptation to gaming architecture. Modifications may comprise 
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erasing or removing selected code from the kernel, modifying code within the kernel, 
adding code to the kernel or performing any other action that renders certain device 
handler code inoperable in normal kernel operation. By modifying the kernel in some 
embodiments of the invention, the function of the computerized gaming apparatus can 
5 be enhanced by incorporating security features, for example. In one embodiment, all 

modifications to the kernel are of the form of proprietary kernel modules loadable at 
run-time. 

In one embodiment, the system is used to execute user level code out of ROM. 
10 The use of the Linux operating system lends itself to this application because the 

source code is readily available. Other operating systems such as Windows and DOS 
are other suitable operating systems. 

Embodiments of the invention include hard real time code 310 beneath the 
15 kernel providing real time response such as fast response time to interrupts. The hard 

real time code 3 10 is part of the operating system in one embodiment. 

In one embodiment of the invention, all user interface peripherals such as 
keyboards, joysticks and the like are not connected to the architecture so that the 

20 operating system and shared objects retain exclusive control over the gaming 

machine. In another embodiment, selected device handlers are disabled so that the 
use of a keyboard, for example, is not possible. It is more desirable to retain this 
fiinctionality so that user peripherals can be attached to service the machine. It might 
also be desirable to attach additional user peripherals such as tracking balls, light 

25 ' guns, light pens and the like. 

In another embodiment, the kernel is further modified to zero out all unused 
RAM. This function eliminates code that has been inserted unintentionally, such as 
through a Trojan horse, for example. 

30 In one embodiment, the kernel and operating system are modified to hash the 

system handler and shared object or gaming program object code or both, and to hash 
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the kernel code itself. These functions in different embodiments are performed 
continuously, or at a predetermined frequency. 

The system handler appHcation is loaded and executed after loading the 
5 operating system, and manages the various gaming program shared objects. In further 

embodiments, the system handler application provides a user Application Program 
Interface (API) 206 that includes a library of gaming functions used by one or more of 
the shared objects 210. For example, the API in one embodiment includes functions 
that control graphics, such as color, screen commands, font settings, character strings, 

10 3-D effects, etc. The device handler callbacks 210 are preferably handled by an event 

queue 320. The event queue schedules the event handlers in sequence. The shared 
object 203 calls the APIs 206 in one embodiment. The system handler appUcation 
202 in various embodiments also manages writing of data variables in the 
"game.state" file 205 into the nonvolatile storage 204, and further manages calling 

15 any callback functions associated with each data variable changed. 

The system handler 202 application of some embodiments may manage the 
gaming program shared objects by loading a single object at a time and executing the 
object. When another object needs to be loaded and executed, the current object may 

20 remain loaded or can be unloaded and the new object loaded in its place before the 

new object is executed. The various shared objects can pass data between objects by 
storing the data in nonvolatile storage 204. For example, a "game.so" file may be a 
gaming program object file that is loaded and executed to provide operation of a 
feature set of a computerized wagering game, while a "bonus.so" gaming program 

25 object file is loaded and executed to provide a feature set of the bonus segment of 

play. Upon changing from normal game operation to bonus, the bonus.so is loaded 
and executed upon loading. Because the relevant data used by each gaming program 
object file in this example is stored in nonvolatile storage 204, the data may be 
accessed as needed by whatever gaming program object is currently loaded and 

30 executing. 
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The system handler application in some embodiments provides an API that 
comprises a library of gaming functions, enabling both easy and controlled access to 
various commonly used functions of the gaming system. Providing a payout in the 
event of a winning round of game play, for example, may be accomplished via a 
5 payout function that provides the application designer's only access to the hardware 

that pays out credit or money. Restrictions on the payout function, such as 
automatically reducing credits stored in nonvolatile storage each time a payout is 
made, may be employed in some embodiments of the invention to ensure proper and 
secure management of credits by the computerized gaming system. The functions of 

10 the API may be provided by the developer as part of the system handler application, 

and may be a part of the software provided in the system handler application package. 
The API functions may be updated as needed by the provider of the system handler 
application to provide new gaming functions as desired. In some embodiments, the 
API may simply provide functions that are commonly needed in gaming, such as 

15 computation of odds or random numbers, an interface to peripheral devices, or 

management of cards, reels, video output or other similar functions. 

The system handler application 202 in various embodiments also comprises a 
plurality of device handlers 210 that monitor for various events and provide a 

20 software interface to various hardware devices. For example, some embodiments of 

the invention have handlers for nonvolatile memory 212, one or more I/O devices 
214, a graphics engine 216, a sound device 218, or a touch screen 220. Also, gaming- 
specific devices such as a pull arm, credit receiving device or credit payout device 
may be handled via a device handler 222. Other peripheral devices may be handled 

25 with similar device handlers, and are to be considered within the scope of the 

invention. In one embodiment, the device handlers are separated into two types. The 
two types are: soft real time 21 OA and regular device handlers 21 OB. The two types 
of device handlers operate differently. The soft real time handler 210A constantly 
runs and the other handler 210B runs in response to the occurrence of events. 
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The nonvolatile storage 204 used to store data variables may be a file on a 
hard disc, may be nonvolatile memory, or may be any other storage device that does 
not lose the data stored thereon upon loss of power. In one embodiment the 
nonvolatile storage is battery-backed RAM. In another embodiment, the non-volatile 
storage is flash memory. The nonvolatile storage in some embodiments may be 
encrypted to ensure that the data variables stored therein cannot be corrupted. Some 
embodiments may further include a game.state file 205, which provides a look-up 
table for the game data stored in nonvolatile storage 204. The game.state file is 
typically parsed prior to execution of the shared object file. The operating system 
creates a map of NVRAM by parsing the game.state file. The look-up table is stored 
in RAM. This look-up table is used to access and modify game data that resides in 
NVRAM 204. This game data can also be stored on other types of memory. 

In some embodiments, a duplicate copy of the game data stored in NVRAM 
204 resides at another location in the NVRAM memory. In another embodiment, a 
duplicate copy of the game data is copied to another storage device. In yet another 
embodiment, two copies of the game data reside on the NVRAM and a third copy 
resides on a separate storage device. In yet another embodiment, three copies of the 
game data reside in memory. Extra copies of the game data are required by gaming 
regulations in some jurisdictions. 

Data written to the game state device must also be written to the nonvolatile 
storage device, unless the game state data device is also nonvolatile, to ensure that the 
data stored is not lost in the event of a power loss. For example, a hard disc in one 
embodiment stores a file that contains an unencrypted and nonvolatile record of the 
encrypted data variables in nonvolatile storage flash programmable memory (not 
shown). Data variables written in the course of game operation may be encrypted and 
stored in the nonvolatile storage 204, upon normal shutdown. Loss of power leaves a 
valid copy of the most recent data variables in the non-volatile storage. 
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In an alternate embodiment, a game state device 205 such as a game.state file 
stored on a hard disc drive provides variable names or tags and corresponding 
locations or order in nonvolatile storage 204, in effect, providing a variable map of the 
nonvolatile storage. In one such embodiment, the nonvolatile storage may then be 
5 accessed using the data in the game state file 205, which permits access to the variable 

name associated with a particular nonvolatile storage location. Such a method 
permits access to and handling of data stored in nonvolatile storage using variable 
names stored in the game state file 205, allowing use of a generic nonvolatile storage 
driver where the contents of the nonvolatile storage are game-specific. Other 
10 configurations of nonvolatile storage such as a single nonvolatile storage are also 

contemplated, and are to be considered within the scope of the invention. 

Callback functions that are managed in some embodiments by the system 
handler application 202 may be triggered by changing variables stored in NVRAM 

15 204. For each variable, a corresponding function may be called that performs an 

action in response to the changed variable. For example, every change to a "credits" 
variable in some embodiments calls a "display_credits" function that updates the 
credits as displayed to the user on a video screen. The callback function may be a 
function provided by the current gaming program shared object or can be called by a 

20 different gaming program object. 

The gaming program's shared objects in some embodiments of the invention 
define the personality and function of the game. Program objects provide different 
game functions, such as bookkeeping, game operation, game setup and configuration 

25 functions, bonus displays and other functions as necessary. The gaming program 

objects in some embodiments of the invention are loaded and executed one at a time, 
and share data only through NVRAM 204 or another game data storage device. The 
previous example of unloading a game.so gaming program object and replacing it 
with a bonus.so file to perform bonus functions is an example of such use of multiple 

30 gaming program shared objects. 
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Each gaming program object may require certain game data to be present in 
NVRAM 204, and to be usable from within the executing gaming program shared 
object 203. The game data may include meter information for bookkeeping, data to 
recreate game on power loss, game history, currency history, credit information, and 
5 ticket printing history, for example. 

The operating system of the present application is not limited to use in gaming 
machines. It is the shared object library rather than the operating system itself that 
defmes the personality and character of the game. The operating system of the 
10 present invention can be used with other types of shared object libraries for other 

purposes. 

For example, the operating system of the present invention can be used to 
control networked on-line systems such as progressive controllers and player tracking 
1 5 systems. The operating system could also be used for kiosk displays or for creating 

"picture in picture" features in gaming machines. A gaming machine could be 
configured so that a video slot player could place a bet in the sports book, then watch 
the sporting event in the "picture in picture" feature while playing his favorite slot 
game. 

20 

The present invention provides a computerized gaming apparatus and method 
that provides a gaming-specific platform that features reduced game development 
time and efficient game operation via the use of a system handler application that can 
manage independent gaming program objects and gaming-specific API, provides 

25 game functionality to the operating system kernel, provides security for the electronic 

gaming system via the nonvolatile storage and other security features of the system, 
and does so in an efficient manner that makes development of new software games 
relatively easy. Production and management of a gaming apparatus is also simplified, 
due to the system handler application API library of gaming functions and common 

30 development platform provided by the invention. 
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Figure 3 is a, diagram illustrating one exemplary embodiment of a gaming 
system 400 according to the present invention including universal operating system 
300. As previously described herein, game layer 402 includes gaming program 
shared objects 203 which are specific to the type of game being played on gaming 
5 system 400. Exemplary game objects or modules include paytable.so 406, help.so 

408 and game.so 410. Game layer 402 also includes other game specific independent 
modules 412. Game engine 404 provides an interface between game layer 402 and 
universal operating system 300. The game engine 404 provides an additional 
application programming interface to the game layer application. The game engine 
10 404 automates core event handling for communicating with the game operating 

system 300, and which are not configurable via the specific game layer game code. 
The game engine 404 also provides housekeeping and game state machine functions. 
The game layer objects 203 and/or modules 406, 408, 410 may also directly call user 
API 206. 

15 

As previously described herein universal operating system 300 is an open 
operating system which allows for conversion of the gaming system 400 into different 
types of games, and also allows for future expandability and upgrading of associated 
hardware in the gaming system 400 due to its open architecture operating system. 

20 

In operating system 300, device handlers 210 provide the interface between 
the operating system 300 and external gaming system input and output devices, such 
as a button panel, bill acceptor, coin acceptor, mechanical arm, reels, speaker, tower 
lights, etc. Each device handler 210 is autonomous to the other. The device handlers 

25 or drivers 210 operate as protocol managers, which receive information from a 

gaming system device (typically in the gaming system device protocol) and convert 
the information to a common open operating system protocol usable by operating 
system 300. Similarly, the device drivers or handlers 210 receive information from 
the open operating system and convert the information to a gaming device specific 

30 protocol. The specific device handlers or drivers used are dependent upon what game 

you are using, and may be loadable or unloadable as independent, separate objects or 



38 



wo 03/023647 



PCT/US02/30286 



modules. The exemplary embodiment shown includes total I/O device handler 414, 
sound device handler 416, serial device handler 418, graphics device handler 420, 
memory manager device handler 422, NVRAM device handler 424, protocols device 
handler 426, resource manager device handler 428 and network device handler 430. 
5 Other suitable device handlers for adapting the operating system 300 to other gaming 

systems will become apparent to one skilled in the art after reading the present 
application. 

Figure 4 is a diagram illustrating one exemplary embodiment of a method of 
10 converting an existing gaming operating system to a gaming system 400 having an 

open operating system 300 according to the present invention. The gaming system 
400 according to the present invention is suitable for converting both video based 
gaming systems and also electrical/mechanical based operating system, such as a 
mechanical reel based slot machine, and combinations of the two in a unit (by way of 
15 a non-limiting example, where one system is an underlying game and the other system 

is a bonus, jackpot or contemporaneous game). Once the existing game operating 
system has been changed over to a universal gaming system 400 having a universal 
operating system 300 according to the present invention, the type of game itself may 
be changed via changing out the game specific code in the game layer 402. 

20 

At 450, the existing game operating system is removed from the game. The 
existing game operating system is typically a proprietary operating platform 
consisting of computer hardware and software which is specific to the game being 
changed out. At 452, a universal gaming system 402 including an open operating 
25 system 300 is installed in the game. At 454, functional interfaces are provided 

between the open operating system and the existing gaming system devices. At 456, a 
game specific program (i.e., game layer 402) is installed in the universal gaming 
system. The game specific program is configured to communicate with the open 
operating system 300. 

30 



39 



wo 03/023647 



PCT/US02/30286 



In one exemplary embodiment, the gaming system according to the present 
invention is used in a mechanical reel-based slot machine, either in a new slot 
machine or in converting an existing slot machine to an open operating system 
according to the present invention. Exemplary conventional reel-based slot machines 
5 include an IGT S-plus slot machine or a Bally^M slot machine. 

Figure 5 is a diagram illustrating one exemplary embodiment of I/O devices 
which must be functionally interfaced within adopting gaming system 402 to a reel- 
based game. The exemplary embodiment shown includes devices which interface 
10 with a digital I/O device driver. In one embodiment, input devices 462 includes a 

button panel device 466, a mechanical arm device 468, a bill acceptor device 470, and 
a coin acceptor device 472. Each of the input devices 462 receives information from 
the specific game devices and provides the information to the gaming system 400 via 
the I/O device driver. 

15 Output devices 464 receive information from operating system 300 which 

provides an output via the I/O device driver to gaming devices 464. In the example 
shown, output devices 464 include reels device 474 which receives an output to the 
stepper motors controlling the reels. Credit displays device 476 which receives an 
output to the LED driven credit displays. Speaker device 478 which receives a sound 

20 output to the game speakers. On-line system protocol devices 480 are communication 

interfaces between the open operating system 300 and the game on-line system. 
Tower light devices 482 receive an interface between the open operating system 300 
and the game tower lights. 

25 Figure 6 is a diagram illustrating one exemplary embodiment of a resource 

manager used in a gaming system according to the present invention. The resource 
manager 500 is a software module which receives a resource configuration file 502 
and stores it in memory 504. In one aspect, memory 504 is stored in nonvolatile 
memory, which in one embodiment is flash memory. The resource manager parses 

30 the resource configuration file and stores individual resources in memory for fast 
recall. 
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In one embodiment, the resource manager 500 stores the file 502 in the form 
of a lookup table. In one preferred embodiment, the resource manager reads the 
configuration files at startup, parses the configuration files and stores them in memory 
5 504. The resource manager file 506 may then be accessed by the rest of the operating 

system 300 software applications. The resource manager operates to map digital I/O 
lines, com ports, game specific resources, kernel modules to load, etc. 

Figure 7 is a diagram of a table illustrating one exemplary embodiment of a 
10 portion of a resource file 506 according to the present invention. The resource 

manager 500 operates to map the input/output (I/O) line to the operating system 
resources. Instead of changing pin locations for different games, the resource manger 
provides for mapping of I/O lines via software. In one aspect, 64, I/O (X8) lines are 
mapped to the various operating system resources. In one aspect, the I/O line at PIN# 
15 1510 is mapped to resource R20 512; and PIN# 2 514 is mapped to resource R3 516; 

PIN# 3 518 is mapped to resource R38 520; PIN# 4 522 is mapped to resource RIO 
524; PIN# 5 526 is mapped to resource Rl 1 528; PIN# 6 530 is mapped to resource 
R12 532; PIN# 7 534 is mapped to resource R13 536; and PIN# N 538 is mapped to 
resource R51 540, etc. 

20 The gaming system 400 according to the present invention is adaptable for use 

as a cashless gaming system. As such, it is useable for converting existing corn-based 
or token-based gaming systems into a cashless gaming system. 

Figure 8 is a diagram illustrating one exemplary embodiment of converting 
25 cash, coin, or token-based gaming system to a cashless gaming system using the 

universal gaming system 400 according to the present invention. References also 
made to Figures 1-7 previously described herein. A card reader or coupon acceptor 
550 and ticket printer 552 are added to the game. The card reader 550 and ticket 
prmter 552 are easily adaptable to interface with the gaming system 400 according to 
30 the present invention. In particular, card reader device driver 554 is added to open 

operating system 300 to enable card reader 550 to communicate with the operating 
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system. Similarly, a ticket printer device driver 556 is added to the operating system 
300 in order to allow ticket printer 552 to communicate with the operating system. 
For example, an existing cash-based reel slot machine can be converted according to 
the present invention to a cashless gaming system. The card reader 550 can operate to 
5 read credit cards, magnetic strip based cards, or accept coupons which includes credits 

such as promotional gaming credits received from a casino. The card or coupons may 
be obtainable from a central or kiosk location. Once play is complete on the gaming 
system 400, the ticket printer 556 is operable to print a ticket representative of the 
amount of credits or money won on the gaming system. The ticket 560 may then be 
10 used as a card or coupon in another gaming system, or alternatively, may be turned in 

at a kiosk or central location for money. 

Figure 9 is a diagram illustrating another exemplary embodiment of the 
gaming system 400 according to the present invention. Due to the open operating 

15 system 300, game layer 402 may be configurable remote from the gaming system 

400, such as on a remote computer or laptop computer 580. Game layer 402 is 
constructed into game objects or modules 302. As such, templates for specific types 
of games are configured to allow a game programmer to specify game specific 
configurable options from a remote computer 580. In another aspect, game specific 

20 modules are created on the remote computer 580. The game layer is then assembled 

and transferred into memory 582. In one aspect, memory 582 is nonvolatile memory 
located in the gaming system 400. In one aspect, the nonvolatile memory is flash 
memory. In one exemplary embodiment, the flash memory is a "Disk on a Chip", 
wherein the game layer 402 is downloaded from the remote computer 580 onto the 

25 disk on a chip 582. 

Figure 10 is a diagram illustrating another exemplary embodiment of 
programming and/or configuring a game layer at a location remote from the gaming 
system 400. In this embodiment, game layer 402 is programmed or configwed on 
30 remote computer 580. After completion of configuring and/or programming game 

layer 402, the game layer 402 is transferred via remote computer 580 to a removable 
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media 584. In one preferred embodiment, the removable media is a flash memory 
card, and more preferably is a CompactFlashTM card. In one aspect, the flash memory 
card plugs into remote computer 580 via a PCMCIA slot. Suitable flash memory 
cards (i.e., a CompactFlash™ card) are commercially available from memory 
5 manufacturers, including SanDisk and Kingston. 

The removable media 584 is removed from remote computer 580 and inserted 
in gaming system 400. In one aspect, removable media 584 can be "hot-inserted" 
directly into the controller board of gaming system 400. The removable media 584 
10 contains game layer 402 including the game specific code and program files. As 

such, removable media 584 remains inserted into gaming system 400 during operation 
of the gaming system. In an alternative embodiment, the game layer 402 can be 
transferred (e.g., via a memory download) from removable media 584 to memory 
inside of gaming system 400. 

15 

In one embodiment, the removable media 584 is maintained in gaming system 
400 during operation of the gaming system. As such, the gaming system program 
files may be verified for authenticity by gaming officials by simply removing the 
removable media 584 and inserting it in a computer or controller used for 
20 verifying/authenticating game code, indicated at 586. 

Figure 1 1 is another exemplary embodiment of a gaming system according to 
the present invention wherein the game layer is programmable or configurable at a 
location remote fi-om the gaming system 400. In this embodiment, game layer 402 is 

25 configurable over a network based communication system. In one embodiment, 

network based system 600 includes a user interface 602, network or network 
communication link 604, and controller 606. Controller 606 is configured to 
communicate with user 610 via network 604. In particular, centralized controller 606 
includes web server 612. User 610 accesses web server 612 via user interface 602, 

30 and downloads a web page suitable for configuring a game layer. In one aspect, the 

web page includes game specific game templates 608, which are utilized for inputting 
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specific user configurations for individual games. Once a game template 608 has 
been configured, the game template is transferred to controller 606 via netvs^ork 604. 
Controller 606 receives the configuration information associated with game template 
608 and assembles game layer or program 402 using the configuration information. 
5 The game layer or program 402 can now be downloaded into memory in gaming 

system 400 for use by gaming system 400 including the game specific configurable 
options determined by user 610. 

The system 600 also allows other user interfaces 614 for configuring games 
10 which may be assembled by controller 606 for use in other gaming systems. 

Alternatively, other user interface 614 may be representative of a gaming official 
checking the game 402 and authorizing use of the game 402 and gaming system 400. 
As such, the game layer 402 may be transferred to the gaming system 400 via 
controller 606, or via a communication link with user interface 614, which may be a 
15 direct connection or may be a network. Alternatively, game layer 402 may be 

transferred from controller 606 or user interface 614 by putting it on a flash memory 
device (e.g., Disk on a Chip or CompactFlash card) and physically inserted into 
gaming system 400. 

20 Network 604, as used herein, is designed to include an internet network (e.g., 

the Internet), intranet network, or other high-speed communication system. In one 
preferred embodiment, network 604 is the Internet. While the exemplary embodiment 
and this detailed description refers to the use of web pages on the Internet network, it 
is understood that the use of other commiinication networks or next generation 

25 communication networks or a combination of communication networks (e.g., and 

intranet and the Internet) are within the scope of the present invention. The 
configuration information received from user interface 602 can be assembled into 
game layer 402 using hardware via a microprocessor, programmable logic, or state 
machine, in firmware, and in software within a given device. In one aspect, at least a 

30 portion of the software programming is web-based and written in HTML and/or 

JAVA programming languages, including links to the web pages for data collection, 
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and each of the main components communicate via network 604 using a 
communication bus protocol. For example, the present invention may or may not use 
a TC/IP protocol suite for data transport. Other programming languages and 
communication bus protocols suitable for use with the system 600 according to the 
5 present invention will become apparent to those skilled in the art after reading the 

present application. 

Figure 12 is a diagram illustrating one exemplary embodiment of web page 
game templates used in the system shown in Figure 11. Template 1 is shown at 622 
and Template 2 is shown at 624. In one embodiment, upon accessing controller 606 

10 via user interface 602, user 610 selects a game type that the user 610 would like to 

either program or configure. An example of a game type is a poker template. Based 
on the game type 626, a template appears at user interface 602 for that game type 
which allows the user to specify game configurable options, indicated at 628. The 
controller then operates to assemble the game layer or game programs 402 based on 

15 the information received via the game template. The configurable options may 

include any type of game specific configurable options, such as game colors, game 
sound, percentage payouts, game rules, game options, etc. 

Figure 13 is a diagram illustrating one exemplary embodiment of nonvolatile 
RAM used in a gaming system 400 according to the present invention, wherein the 

20 nonvolatile RAM is configured as a redundant memory system. In one exemplary 

embodiment shown, the nonvolatile RAM is configured as a RAID system. In the 
hard disk drive industry, RAID (short for redundant array of independent disks) 
systems employ two or more disk drives in combination for improved disk drive fault 
tolerance and disk drive performance. RAID systems stripe a user's data across 

25 multiple hard disks. When accessing data, the RAID system allows all of the hard 

disks to work at the same time, providing increase in speed and reliability. 

A RAID system configuration as defined by different RAID levels. The 
different RAID levels range fi-om LEVEL 0 which provides data striping (spreading 
out of data blocks of each file across multiple hard disks) resulting in improved disk 

30 drive speed and performance but no redundancy. RAID LEVEL 1 provides disk 

mirroring, resulting in 100 percent redundancy of data through mirrored pairs of hard 
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disks (i.e., identical blocks of data written to two hard disks). Other drive RAID 
levels provide variations of data striping and disk mirroring, and also provide 
improved error correction for increased performance and fault tolerance. 

In Figure 13, one exemplary embodiment of RAID data storage system used in 
5 a gaming system 400 according to the present invention is generally shown at 630. 

The RAID storage system 630 includes a controller or control system 632 and 
multiple nonvolatile RAM data storage units, indicated as RAMA 634 and RAMB 
636. In one aspect, RAMA 634 and RAMB 636 each include a backup power system 
PWR 638 and PWR 640. In one aspect, backup power systems PWR 638 and PWR 

10 640 are battery backup systems. RAMA 634 and RAMB 636 are configured to 

communicate with control system 632 as a redundant array of storage devices. 
Preferably, nonvolatile memory RAMA 634 and nonvolatile memory RAMB 636 are 
configured similar to a RAID level configuration used in the disk drive industry (i.e., 
as a "mirrored pair"). Nonvolatile memory RAMA 634 and nonvolatile memory 

15 RAMB 636 communicate with control system 632 via communication bus 638, using 

a communication bus protocol. One exemplary embodiment of a communication bus 
suitable for use as communication bus 638 is an industry standard ATA or uniform 
serial bus (USB) communication bus. Control system 632 includes a microprocessor 
based data processing system or other system capable of performing a sequence of 

20 logical operations. In one aspect, control system 632 is configured to operate the 

RAID system 630 nonvolatile memories RAMA 634 and RAMB 636 as a mirrored 
pair. As such, read/write to nonvolatile memory RAMA 634 are mirrored to 
nonvolatile RAMB 636, providing redundancy of crucial gaming specific data stored 
in nonvolatile memory RAMA 634 and RAMB 636. Alternatively, the nonvolatile 

25 memory RAMA 634 and nonvolatile memory RAMB 636 may be configured to 

communicate with control system 632 similar to other RAID storage system levels, 
such as RAID LEVEL 0, RAID LEVEL 2, RAID LEVEL 3, RAID LEVEL 4, RAID 
LEVEL 5, RAID LEVEL 6, etc. Further, the RAID system 630 may include more 
than the two nonvolatile memories RAMA 634 and RAMB 636 shown. 

30 Although specific embodiments have been illustrated and described herein, it 

will be appreciated by those of ordinary skill in the art that any arrangement which is 
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calculated to achieve the same purpose may be substituted for the specific 
embodiments shown. This application is intended to cover any adaptations or 
variations of the invention. It is intended that this invention be limited only by the 
claims, and the full scope of equivalents thereof. 
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Chapter 1 — Introduction 



A. A Universal Game Design Approach 

Until now the countless video and mechanical games of chance offered for sale have not been 
at all standardized. Programmers often had to create new code in each new game, for every 
function, and for each hardware apparatus. 

Shuffle Master's new Game Operating System (SGOS) brings a universal game design 
approach to electronic games of chance. SGOS includes pre-approved software that handles 
all common game functions and security features without the need for new code. 

For simplicity, this manual will refer to the Shuffle Master Game Operating System software 
as SGOS, 

B. Uses the Stable Linux Platform 

SGOS runs on the Linux Operating System. The relatively new Linux platform (conceived in 
1991, first introduced more widely in 1994) is fast becoming a favorite for countless embed- 
ded applications because it is much more lean and stable than Windows. 

SGOS is written in C and C-H-. You need to have some basic programming skill to create 
games with the provided templates. You should be proficient in C and C++ if you will be 
designing new games from scratch, 

C. Key Game Features 

SGOS takes care of all game actions and hardware interfaces. Functions common to all games 
are pre-approved and located in the SGOS library. Key features of SGOS are as follows: 

• All except game personality is pre-designed and pre-approved 

• Game initialization and power loss recovery 

• Included engines: Draw Poker, Video Reel and Mechanical Reel 

• Support for design of new game engines by developer 

• Supports both single and multi-game platforms 

• Complete animated graphics engine 

• Game history and accounting 

• Stereo sound support 

• Advanced security features 

• Drivers for all video game hardware 

• Remote debugging 

• Online protocol support 

• Basic level game development requires only graphic and text changes 

• Advanced level game development allows complete design of graphics, soimd, and 
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D. Developing a New Game with SGOS 

The SGOS Software Development Kit supports two levels of development: 

1 . Basic . Use the included game templates (e.g. 9-line) for an immediate design. With a 
few interesting graphics and minor code changes, a casino tech or other designer can 
quickly create a unique new casino game. 

2, Advanced , Powerful and flexible platform for a totally new game design. 

You can quickly design a unique game with one of the provided game templates, design a fully 
new game with the generic template, or mix the two approaches for efficient best results. How- 
ever you proceed, your programming time will be slashed with the pre-designed and pre- 
approved underlying features of SGOS. You can focus on the new aspects of your game 
design. 

E. Potential Users 

Any entity that sells, uses, or designs video games of chance can use the Shuffle Master SGOS 
to develop a unique new game. The most likely users include the following: 

1 , Game Manufacturers . Manufacturers can save a great deal of design and approval time 
by using Shuffle Master's SGOS. A manufacturer can create a new game as unique and 
complex as desired. 

2, Casino Operators . With the SGOS platform, a casino can design its own games. Using 
one of the included game engines and included tools, the casino's programmer can cre- 
ate a unique game with new graphics and a new name. 

3, Third Party Developers . A third party programmer or developer may provide a new 
game design for either a manufacturer or a casino. 

R Target Machines 

The examples used in this documentation are based on building a new machine with all new 
hardware. Refer to Part VL HARDWARE SOLUTIONS in this book for details about com- 
monly supported hardware. 

The same game approach will apply for conversion of existing video or mechanical machines. 
However, the hardware and software interfaces for existing components are very application- 
specific and are outside the scope of this documentation. 
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Chapter 2 - Installing and Configuring SGOS 



A. Pre-loaded Development System 

If you have a preloaded development system from Shuffle Master, you can skip this chapter 
and start working with SGOS. 

B. Install Linux 

If you do not already have it, first install Linux on the computer you will be using for game 
development. Refer to Appendix A for suggestions if you are new to Linux. Red Hat Linux 6.x 
is preferred, but other Linux packages should be satisfactory. 

You can use the most current version of Linux on your development machine, but the build 
machme must use the Linux version included with SGOS. The Linux OS is a part of the pre- 
approved code. 

Neither Linux nor SGOS is greedy for RAM or hard drive space. You should have at least 32 
MB of RAM and 500 MB available hard drive space for a comfortable development environ- 
ment.. 



TIP.., You can set up your computer as a Windows/Linux dual-boot system. Neither Linux 
nor SGOS will require very much of your hard drive space. Also, some vendors offer a 
Linux operating system that runs in Windows. Though it is less efficient, it might be easier 
to install. 



C. Install SGOS 

Install the SGOS library and game development files from the SGOS CD-ROM. When you 
msert the CD-ROM it will lead you through a menu-driven installation. 

1 . ***Add notes here based on final installation CD. 

2. If you want to load the tutorial files now, create a directory named... ***add notes 

The file tree in Figure 10-1 shows where the CD-ROM install procedure will place files by 
default. 

File Formats 

.ps.Z compressed PostScript file, for UNIX 
.tar UNIX archive file 

.tar.gz compressed UNIX archive file-"tar fwxz file_name"(to unzip and untar) 
.gz UNIX compressed archieve file using gzip-"gunzip file^name" to uncompress 
.bz2 Advance compressed UNIX archive file-"bunzip2 file^name" to unzip 
,exe Windows executable program 
.zip Windows archive file 
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Z.D - Disable Functions not Supported by Development Platform ^"^g 



D. Disable Functions not Supported by Development Platform 

SGOS configuration files end with an .oti extension. The file mygarae.oti provides all settings 
for the enabedded system on a target machine. For your desktop development system, you also 
must include I oca I . oti if you want to disable hardware that is not supported by your develop- 
ment machine. Refer to Appendix D for the various »oti file listing and the default version of 
local .oti , which disables the touch screen and other hardware typically not available on a 
desktop computer running on Linux. 

Note that soimd is disabled by default, since sound is a bit more complicated to set up on the 
Linux platform. Modify I oca I . oti as needed for your development setup. 



TIP... If your mouse does not work, you probably need to change your svgalib settings, as 
follows: 

1 . Find /etc/vga/l I bvga , conf i g in the root directory, and open it for editing. 

2. Look for your mouse manufacturer and uncomment the appropriate line, 

3. If your mouse still is not working, try reversing mouse^accel _type to ON or OFF, 

4. You can modify many other mouse settings in this configuration file. Review a Linux 
manual for fiirtiher suggestions. 



E. Tools Available on the Web 

The menu-driven setup process should give you a satisfactor}' installation. If you are new to 
the Linux operating system, a Linux manual will help you get up to speed. If you have any 
problems with the SGOS installation, first look at the README file. Also check the Shuffle 
Master Web site at shuff I enastersupport. com. 
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Chapter 3 — SGOS Components 



A. Basic SGOS Layout 

Although you cannot access the SGOS precompiled library layer directly, it will be helpful to 
see how it interacts with the game layer and your game program. 

1. Library Layer 

Figure 3-1 shows the basic layout of SGOS. The bulk of SGOS resides in the library, 
including the Linux kernel, drivers, event handler, user API, and watchdog. The library 
tracks all game history and accounting and handles hardware interfaces. The library code 
is pre-compiled and caimot be directly accessed. 
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3.B - Linux Real Time and Linux Kernel 



2. Game Layer 

With the numerous pre-approved features provided in the SGOS library, you will need 
only a few configuration and object files to develop a new game. The rest of this document 
will explain how to set up a new game, either by modifying the included game templates 
or designing a game from scratch. 

Version 2.0 of SGOS includes 9-line, draw poker, and generic game templates. Chapter 
10 describes each of the files you will need to create a working game. 

B. Linux Real Time and Linux Kernel 

Linux 2,2.13 is the operating system for Version 2.0 of SGOS, For consistency with any state 
game agency approved code, the Linux version of the SGOS library cannot be changed. How- 
ever, you can develop your game in a newer version of Linux. Refer to Appendix A if you are 
new to the Linux platform, 

a User API 

The User API defines all library function calls that can be made firom the game layer. The 
functions called out by the User API provide powerfiji graphic, sound, and other development 
options. 

Chapter 5 and the tutorials in Part IK API TUTORIAL give an overview and examples of pro- 
gramming the user, engine and game API functions. Appendix C provides a complete listing * 
which contains the API functions. 

D. Event Handler 

Timers and their callback functions are what move a game along in SGOS. The timers are usu- 
ally tied to graphic events, and may be launched fi-om either of two places: 

1. The SGOS game engine (you carmot directly control these callbacks). 

2. Your game (you launch timers with the API timer functions). 

The event handler queue receives events as they are called, and handles them in the order 
received. A key feature of SGOS is that events are not threaded together. If a particular event 
fails, the program will in most cases continue to run. The tutorials show the importance and 
role of timers, callbacks and the event handler in SGOS programming. 

E. NVRAM AND GAME STATE 

"Game states" such as BEGINPLAY, PLAY1, and EVALUATE are held in nvram and contain current 
and historic game data. Game state values provide data to run the current game, display game 
history, or resume a game where it left off in the event of a power failure or other program dis- 
ruption. Table II-I lists the primary game states and related callback functions that serve as 
"hooks" into the game engine. 

The pre-approved game engine effectively "runs" the game and handles all game accounting 
and history. Your game code uses the "hooks" to direct the game engine and create a new game 
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personality, by defining how the game state callback functions are handled. Chapter 11 and 
tfie tutorials in Part V. GAME ENGINE TUTORIAL explain SGOS's important game state fea- 
tore. It IS an innovative and different approach to game design. The examples will help you 
discover how to work with game states and callback functions in SGOS. 

F. Watchdog 

P^"?™' ^ °" ^^^^ s^sm^ni of RAM at regular intervals. The device 
Hbraty ^® ^^t^^'^og »s part of the pre-approved SGOS 
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Chapter 4 — Tips to Get Started with SGOS 



A. Unique Aspects of SGOS 

The SGOS library and user interface are programmed in C and C++. If you are an experienced 
programmer you probably want to get going with SGOS programming! 

Because the pre-approved game engine and library are hidden, you need to know the basics of 
how they work and how to interface with them. Especially, you will need to understand the 
following key aspects of the SGOS approach: 

• How SGOS uses timers and nvram to run the game. 

• How and when to interface with the game engine and game library, especially with the 
API functions and "game states". 

If you skim over the preliminary chapters, keep an eye out for these key concepts, 

B. About the Examples and tutorials 

The examples and the tutorial files help to show the unique aspects of SGOS. The files are 
included on the CD-ROM. You can run them to see simple applications of buttons, timers, 

nvram, and other SGOS features. 

■ -A 

SGOS includes over 100 API functions. The tutorial examples show use of API functions for 
basic game routines such as buttons and animation. See Appendix C for a complete listing of 
the functions. 

The API calls access the SGOS library directly, whereas the callbacks to advance the game 
states are made via the game engine. To get a quick overview of how these important functions 
differ and how they are used, refer to Appendix C and Figure 11-1, 
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//. PROGRAMMING WITH THE API 



Chapter 5 - Scope of userapi Functions 
Chapter 6 - Timers, Buttons, and Callbacks 
Chapter 7 -Handling Graphics 
Chapter 8 - Sounds in SGOS 
Chapter 9 - Non-Volatile RAM (nvram) 
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Chapter 5 — Scope of userapi Functions 



A. Role of userapi in SGOS Programming 

Your game code cannot make standard C calls to the library, including file I/O and the pri ntf 
family. Instead, SGOS provides a large and versatile set of API fimctions for all the needed 
routines to create a game, userapi , h and engi ne_api . h declare these functions, and you make 
them available by including userapi , h when you build your game. 

Like the rest of the library the API is pre-approved and cannot be changed by the programmer, 
Periodic new SGOS releases will add features. You can also make requests for new API func- 
tion calls on the support Web site, shufflemastersupportcom. 

Appendix C provides a full listing of the API functions with explanations. 

B. Overview of userapi Functions 

1. Graphic Routines 

The API includes over fifteen graphics functions to draw and manipulate various shapes. 
An example of a typical graphics function format and variables passed is 

gfx_drawbar(int x, int y, int w, int h, int c) 

which draws a solid rectangle at x, y with width w, height h, and color c, 

Several of the graphics functions, including background, buffer and sprite routines are 
used for animations. The examples in IK API TUTORIAL provide progressive examples 
of how to handle graphics in SGOS with these functions. 

2. Widget Routines 

*** edit this section when we figure out the widget functions 

Six widget functions create buttons, set their properties, and enable/disable them. Though 
all buttons have the same ability to launch an event, SGOS includes three distinct widget 
types: text only, graphic, and a graphic that changes when the button is pressed. 

The *'hot spot" function works the same way, except that it does not create any button bor- 
der, text or graphics. It simply defines an area of the screen that responds like a button if 
pressed. You can use it for any piupose — for example, to create a button-type response to 
an area of the screen which a player is intuitively drawn to. 

Buttons in SGOS can be disabled and covered with a new button, but cannot be modified 
or removed until the current module is closed. You may want to use the hot spot along 
with defined rectangles to build more complex button schemes which can handle changes, 

3. Module Handling Routines 

Three module routines load, jump and exit a module, and either save the current module 
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name for retrieval or revert to the previous remembered module. 

4. Timer Routines 

The two timer routines — tiner^start and timer^ki II — are very important in SGOS 
event driven programming. For more information refer to Chapter 6 and Ihe tutorial exam- 
ples in Chapter 20, Chapter 7P, and Chapter 2L 

5. Non-volatile RAM Routines 

The nvram routines manage stored raygame. state values on the nvram hardware (or in the 
nvram file on the development platform). The game application caimot directly touch 
nvram. All game manipulations and retrievals of nvram occur through API functions. 
Refer to Chapter 9 for an explanation of how the SGOS nvram manager works. 

The eighteen API functions that work with nvram perform any of the following three 
actions on the six different types of strings (char, short, int, long, float, double): 

1. Set a value 

2. Retrieve a value 

3. Increment a value 

6. Sound Routines 

API sound routines are available to play or stop ,wav sound files and set the master vol- 
ume level. 

7. Mechanical Reel Routines 

Specific routines targeted for use with mechanical reel slot machines. Refer to Appendix 
C 

8. External Display Routines 

Specific routines targeted for use with external displays. Refer to Appendix C 

9. Text Formatting Routines 

Three text formatting functions are available for formatting text and numbers, 

10. Resource Routines 

11. System Routines 

Miscellaneous API routines include a random number generating routing, setting a lamp 
defined within the .oti file, and debugging routine. For setting up the debug and for setting 
a breakpoint refer to Chapter 14-E, Debugging Tools, Two revision information functions 
return strings with the version and release date of the running version of SGOS. Note that 
the user's game version is set in the file "version" in app. temp. This file is created/updated 
at compile time. 
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12. Engine NVRAM Routines 

These API calls let you check values in the engi ne. state and other parameters set by the 
game engine. 

13. IVIuitigame IVIanagement Routines 

14. IMiscelianeous Game Engine Routines 

15. Game Specific Routines 

Refer to Appendix C for API calls that are specific to nineline or draw poker games. 
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Chapter 6 ~ Timers, Buttons, and Callbacks 

A. Event-Driven Programming 



A game in SGOS is event-dfiven. Timers and their callback functions are the motive force in 
SGOS that cause a game to proceed and move along. The timers are usually tied to graphic 
events or player events such as a coin drop or button press. A timer can launch from either of 
two places: 

1, The SGOS game engine (you cannot directly control these callbacks). 

2. Your game (you launch timers with the API timer functions). 

Even though you can react to or create events from the game side, every event is actually ser- 
viced on the library side of SGOS. 

B. Launching Timers 

In an SGOS game, you launch all timers and timer callbacks using the API timer routine: 
tlmer_start(long timeout, char'*' callback) 

This function passes the timeout period in milliseconds (1000 milliseconds = 1 second) and a 
callback function name (not a pointer). Once you start a timer, it times out, then sends the 
event (the callback function) to the event handler queue, which handles all timer events in the 
order they are received. 

Note that char* cal I back is not called with any parameters. You must declare timer callbacks 
as vol d functions* 

C. Multiple and Periodic Timers 

By default each timer is good for only one call You can start multiple timers either by calling 
each one separately, or by setting up a periodic timer. 

1. Starting Multiple Timers 

You can start as many timers as you need, each with a separate call to ti mer_start(). It is 
acceptable to call the same callback multiple times; the event handler will track each 
occurrence. For instance, 

tiiner_start(100, "draw.screen"); 
tiroer_start(200, "draw^screen"); 

will call draw_screen() in 0.1 and 0.2 seconds from now. 

SGOS has a system limit of 60 timers at any one time. You should never need this many 
active timers, but the limit is in place because more than 60 timers can create a bottleneck 
on a typical processor for a target machine. 
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2, Setting Up Periodic Timers 

Create a loop where the callback function's last step re-initiates the timer to call itself 
back. This manual will refer to a timer that calls itself back as a **periodic timer." Chapters 
20 and 21 show tutorial examples that use periodic timers to launch several animated balls 
that move around the screen. 



41 



NOTE... Events in SGOS are not threaded together; if a particular event fails, the program 
will in most cases continue to run. With periodic timers (with callback functions that call 
themselves back) you can start animations once and not have to worry about them again. 



Chapters 19, 2ft and 21 show examples of how to use API timer routines. 



D. Using Timers for Screen Updates 

SGOS event-driven programming makes extensive use of timers. With every event on its own 
timer you can easily add and remove items from the screen. 

Timers are not associated to numbers, so it can be a puzzle to track a particular timer through 
the debug, out file. Looking in the debug, out file is more useful to see how many timers are 
executing at one time, 

E. Using Timers for Animation 

You can create single or periodic timer events. A single timer event occurs once, after a speci- 
fied number of milliseconds. A periodic timer event occurs every time a specified number of 
milliseconds elapses. The interval between periodic events is called an event delay. Periodic 
timer events with an event delay of 10 milliseconds or less consume a significant portion of 
CPU resources. 

The relationship between the resolution of a timer event and the length of the event delay is 
important in timer events. For example, if you specify a resolution of 5 and an event delay of 
100, the timer services notif>' the callback function after an interv^al ranging from 95 to 105 
milliseconds. A mix of logic and experimentation are your best tools to find the right ranges 
for your game design. 

R Killing Timers 

You can cancel an active timer event at any time by using the tl mer.ki 1 1 (char* cal I back) 
function. 



WARNING! Be sure to pass in the timer name. If you pass a null, the function will default 
to killing all timers, including all operating system timers. This will cause the system to 
crash. 



Note that the multimedia timer runs in its own thread. 
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G. Button Events 

The SGOS API offers three button types and a "hot spot." (Refer to Appendix 3 and Chapter 
19 for details and examples of button behavior). The buttons and hot spot each look different 
on the screen, but they all launch an event in the same fashion.They define a screen area that 
triggers a callback when touched on the touch screen (or with a mouse click on your develop- 
ment computer). 

For example, 

raakebuttoni (char* name, int x, int y, int w, int h, int basecolor, char* 



defines a simple button with the text string char* name. When pressed, the button calls char* 
cal I back, and the callback function is placed in the event queue. It works the same as the timer 
callbacks discussed above, but without a timeout period. The button serves as another event in 
the event-driven SGOS scheme. 



cai I back) 
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Chapter 7 - Handling Graphics 



A. A Different Approach to Graphics 

You will likely find the SGOS approach to graphics and animation to be different from other 
approaches you have used. At first the event-driven programming, timer callbacks, and graph- 
ics routines may seem indirect compared to typical C programming. But as you spend time 
with it you will probably come to see it as a very powerful, flexible, efficient, and even "for- 
giving" programming environment 

B. XPM Graphic Format 

The XPM graphic format is a pixel-by-pixel array of an icon's colors. You must convert all 
your game graphics to XPM format to work with SGOS API routines. 

You can compile the converted XPM graphics directly into your program or else have SGOS 
load them from files. Compiling them into the program improves performance, especially on 
the embedded system. This manual refers to the graphic items you include in your program as 
"icons." 

• Transparency images need to be set to RGB value (255,0,255). 

• Save the image with transparencies in a file format such as TIFF (which does not dither 
the image). This way the non-transparent image will not have a halo around it. The 
halo is caused when the file format such as JPG dithers the image edges. Any color 
other than RGB (255,0,255) will not be transparent. 

• All animations need to be saved as separate frames. Later enhancements may include 
the ability to play AVI or MPEG files. 

• ,To conserve memory, try and make all animations with as few frames as possible. For 
example, use one image to show any static picture instead of multiple images at rest 
Make all frames of animation the smallest size to show all the animation sequence. The 
bigger the image, the more memory it uses. In other words, why use the entire screen 
with transparent color backgroimd when the animation takes place in only a fraction of 
the total screen area. 

Several of the API routines support transparency, as discussed in Sections G and H of this 
chapter. 

C- Converting Icons to XPM 

SGOS provides a Python script tool, convgfx. py, to convert your graphic icons to XPM arrays. 
The script converts your graphic image files, organizes them into named XPM arrays in a new 
C file, and creates a related header file. 

The basic approach to use convgfx. py is as follows: 

1. Put all your graphics files in one directory (typically app. temp), 

2. Each icon filename becomes its XPM array name. For example, either lcon1.tif or 
i coni .j pg will convert to an XPM array named i conl (the file extension is dropped). 

3. When you run convgfx. py, it will stuff all the icons into a new ,cpp file and create a 
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header file. For instance, typing 

[app.temp] # ./convgfx.py inygame_i cons 

at the prompt creates myganie_i cons, cpp and mygame^l cons, li. 

Chapter 17 shows the use of convgfx.py in a tutorial example. Appendix G lists the con- 
vgfx. py file. You may want to modify it to fit your particular needs. 

D. Organizing Icon XPM's 

After you create the .cpp file containing all your XPM icons, you can take the further step of 
organizing logical icon groups into arrays. You will probably want to collect the icons for each 
animation in your game into an array. For instance, an array named anination_1[] might 
include i coni, i con2, i con3, etc. 

You can spread your icons among several files, or even maintain a separate file for every icon 
However, it is usually simplest to include all of your graphic icons in a single file. File Listing 
7-1 shows an excerpt of the first few lines from a file that lists all XPM-formatted icons for a 
nineline game. 

Note that this file {File Listing 7-1) has been rearranged into logical arrays for housekeeping. 
The example includes one array for all of the bitmap reel icons, plus other arrays and single 
icons as required for the ganie (not all are shown in the excerpt). The first array, starting on 
Ime 6, names all of the icons for the reel strips. The second array, starting on line 19, lists the 
icons for a very simple animation that happens to include one of the reel icons. 

The file also contains named icons that are not members of arrays. The XPM listing of the first 
icon, named be! I , begins on line 25. Note in lines 26 and 27 that the numbers inside the double 
quotes define a 120 x 120 pixel array using 255 colors given as two-character ID's. 

The pixel-by-pixel array appears immediately after the colors, in this case using two-character 
ID'S. Line 29 shows the beginning of the lengthy pixel-by-pixel color listing. SGOS also sup- 
ports single character ID's for files with fewer colors. See File Listing 17-1 for an example of 
an XPM listing for a simple ball icon. 
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File Listing 7-1: nineline_gfx.cpp, Example of xpm Listing 



1 


#i ncl ude "userapi , h" 


2 


/ XPM ^/ 


3 

A 


#i ncl ude "ni nel i ne„gfx» h" 


4 
5 


// An array containing all the icon bitmaps 


6 


const char* const * icon_bitmaps[] = { 


7 


whambutnOI, 


8 


cherri es, 


9 


oranges r 


10 


mel on, 


11 


pi um, 


12 


crui se02. 


13 


ri ng02, 


14 


car 02, 


15 


bi gbucksOl , 


16 


pyl 1 ogoOl , 


17 


pwhain201 


18 


{; 


19 


const char* const * bi gbucks_anira[] = { 


20 


bl gbucksOl, 


21 


bi gbucks02. 


22 


bi gbucksOl, 


23 


bi gbucks02 


24 


}; 


25 


const char* const bel 1 [] = { 


26 


/* width height num^colors chars_per_pi xel */ 


27 


" 120 120 255 2", 


28 


/*col ors*/ 


29 


"..c #54214", 


30 


".#c #baad09", 


31 




32 


etc rest of the col ors 



See File Listing 17^2 for a more complete example of a simple XPM graphic. 



E. THREE Graphics Buffers: Screen, Background and Frame 

The following three buffers are available to manipulate graphics in SGOS: 

1. GFX^SCREENBUFFER - Whatever is drawn to the GFX^SCREENBUFFER will display on the 
screen. 

2. GFX JACKGROUNDBUFFER The GFX JACKGROUNDBUFFER is generally for storing the com- 
plete original GFX^SCREENBUFFER. You can use various API routines to restore the 
GFX.SCREENBUFFER when you remove or relocate icons, 

3. GFX^WORKBUFFER - This buffer is optional. The GFX^WORKBUFFER provides more options 
for how you assemble icons before drawing them to the screen buffer, especially for 
more complex animations. 

R Setting the Buffer Context for API Functions 

The API graphics routines can interact with any of three buffers. To use these routines you 
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must first set the proper buffer, or "context", with the API call 

gfx_setcontext(int context) 
where context is one of the three buffers: GFX^SCREENBUFFER, GFXJACKGROUNDBUFFER, or 
GFX.WORKBUFFER. The SGOS library assigns integer values to control the outcome of all API 
routines that need to know the context. 



TIP... You do not need to reset the context if you can logically determine that the most 
recent setting is the one you need. If quite a few lines of code have occurred since the last 
context was set, you may want to set it again to protect against future inserted code. 



G. Colors Reserved for Transparency 

SGOS assembles a transparency by replacing a graphic's transparent pixels with pixels from 
the active screen or the buffer (depending on the function used). You must use the right func- 
tions and buffer contexts in the ri^t order to get appropriate transparency results. 

SGOS enlists a transparency buffer whenever you use an API routine that includes transpar- 
ency. For color schemes that can be covered by single hexidecimal characters (i.e. 45 or less) 
the graphics conversion tool will assign the character 9 to transparent pixels. For larger color 
schemes it will assign the two characters 99. Both of these equal pure magenta. 



WARNING! Pure magenta is not a common color in most artwork. If it does appear in a 
graphic that also includes transparency, you will get improper results — all of the pure 
magenta pixels will show up as transparent since they are defined by the same characters (9 
or 99). You will have to shift the pure magenta to a slightly different color in your original 
graphic to keep it from being treated as a transparency. 



H. "Trans" and "Sprite" Transparency Functions 

Both the "Trans" and "Sprite" types of API transparency routines create transparency by sub- 
stituting pixels from a buffer. The two types of functions can sometimes accomplish the same 
task, but they differ considerably in how they process data. 

Key aspects of the Trans routines are as follows: 

• They let you define a transparency color (can be any color). 

• They get transparency pixels only from the BACKGROUNDBUFFER. 

• They are drawn to a special interim buffer,* 

• They are not cached; they are slower, especially on a target machine. 

• They are best for static screen updates or very low level animation, 

*A notable Trans exception is that by calling gfx^drawpartXPMQ loaded with all -J arguments 
you can cache the entire graphic, as a sort of pseudo-buffer 

Key aspects of the Sprite routines are as follows: 

• They always use a transparency color of 99 or 9. 

• They can get their transparency pixels from any of the three buffers. 

• They offer a fill instead of transparency with setspr i tetype (SPRI TEF I LL) . 
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• They are cached and have no interim buffer; they are much faster, 

• They are the tool of choice for complex animations, 

The discussion of animation approaches in this chapter and the tutorials in Chapters 19, 20, 
and 21 will help you see the applications of the various transparency functions in SGOS. 

1. Drawing to the Three Buffers 

All three graphics buffers in SGOS use an area of memory with the same number of bytes as 
the screen. Multiple API functions can draw strings, lines, bars or graphic items to any of the 
three buffers - GFX^SCREENBUFFER, GFX^BACKGROUNDBUFFER or GFX^WORKBUFFER, whichever is set 
as the current context. Many of these functons use the syntax gfxjdra^iifname of action] 0- 
Some of the draw functions flip or otherwise manipulate a drawn item, and/or draw it as a 
transparency. The API button calls (e.g. nakebuttonIO) should' only be made to the screen 
(context set to GFX^SCREENBUFFER), to ensure that proper functionality is available on the 
screen. Once a button is created, you can update the button's graphic properties (e.g. setbut- 
toncol or()) in either context. Make sure that you modify button properties on the background 
buffer if you are going to copy the background to the screen. 

See the tutorial in Chapter 19 and the API calls in Appendix C for more about handling the 
graphics aspects of buttons. 

J. Updating Among Buffers with gfx_copybuffer() 

The API function to copy to or from the different buffers, is 

gfx_copybuffer() - copi es al I or part of one buffer to another 

You will be using this function extensively as you make animations in your game. 

K. Limited Animation Using Only the Screenbuffer 

The simplest animation to set up in SGOS is a series of rectangular icons without transparency 
that remain in a fixed area of the screen. In this simple case, you can draw each new icon and 
simply let it replace the prior one. Neither the GFX^BACKGROUNDBUFFER nor GFX.W0RK8UFFER 
would be needed. 

However, you will need at least the GFX_BAGKGROUNDBUFFER if you have any of the following 
very common animation criteria: 

• Transparency 

• Change in icon size or position 

• Overlap with any other updated icons 

Without another buffer in these cases, you might get lingering fragments from prior icons, 
absent background areas, or unwanted transparency fills. 



L. Using the BACKGROUNDBUFFER for Transparency 

You can store an exact copy of your GFX^SCREENBUFFER to the GFXJACKGROUNDBUFFER at any 
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point with gfx_copybuffer(). The "Trans" functions use the current data in your 
6FX_BACKGR0UNDBUFFER to fill in transparent pixels. (The "Sprite" functions can use any of the 

three buffers, whichever is set as the current context.) The tutorial examples in Chapters 17 
and 18 show examples of how transparency works in SGOS. 

You will generally want to create your initial screen and copy it to the GFX.BACKGROUNDBUFFER 
rr5°cr,>cc«oS ^''■■^^'^ c'^^ges or animations. All buttons must be created to the 
' ^^pCREENBUFFER so they can launch appropriate functions with the mouse or touch screen 
(Also refer to the discussion of buttons in Chapter 6 and the tutorial example in Chapter 19. 

M. Double-buffered Animation 

Besides being the most likely source of transparency pixels, the GFX BACKGROUNDBUFFER is nec- 
essary for any screen change or animation that requires graphics data from the original screen. 
For double-buffered" animations, the GFX_BACKGROUNDBUFFER is the repository for restoring 
pixels when you move any icon to expose an area that must be restored to the origmal screeS 
content. ^ 
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Figure 7-1 - Use of GFX_BACKGROUNDBUFFER for a Screen Update 

Figure 7-1 shows an elementary way to use the background buffer in an animation, as follows: 

1 . Create a screen using API functions as needed, then create a duplicate background 
buffer using 
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gfx_copybuffer(x, y, w, h, destx, desty, GFX_SCREENBUFFER, GFX_BACKGROUNDBUFFER) 
mcy°^^ °^ ^^^^ '^'^"^ "^'"^ ™^ following functions which support transpar- 

• "Trans" functions — gfx_dra«rt:ransXPM(), gfx_drawtransFi I e(), or 
gfx_rotatetransXPII() 

• "Sprite" functions — gfx.drawspri te () , gfx.drawspr i tef 1 1 pped () 
gfx_drawspri tepart(). or gfx.drawspritepartfl i pped(). First set the graphics 
context to the GFX_BACKGROUNDBUFFER and the sprite type to SPRITETRANS with 
gfx_setgraphicscontext() andgfx_setspritetype(). (Note that the graphics con- 
text has no effect on the "Trans" functions, because the context is hard-wired for 
these functions.) 

3. Wrong way and right way: Step 3 in Figure 7-1 shows what happens if you merely re- 
draw the icon to a new location. The old icon remains, and the new one is placed next 
to it. 

rf *® "^^^ to erase the old icon and restore that area of the screen. 

Use the API call 

gfx_copybufferpart([source (x,y,w,h)], [desti nation (x,y)], 
GFX_BACKGROUNDBUFFER, GFX_SCREENBUFFER) 

to retrieve the needed rectangle. Depending on how you first drew the icon, you may 
need to call gfx_getdi mens! onsXPH() to find w and h. 

4. Now you can successfully draw your new icon to the new location (this simple exam- 
ple draws the same icon to a new location), using an appropriate trans or sprite API 
call. 

N. Role of Timers and Callbacks in Animations 

SGOS event-driven programmmg relies heavily upon timers and callback functions to carry 
out animations. With every event on its own timer you can easily add and remove items from 
the screen. Also by using functions which call themselves back via timers, you can start ani- 
mations and let them run. You can let another event modify the animation or kill the timers. 

Refer to Chapter 6 and the tutorial examples in Chapters 20 and 21 for more about animation 
using timers, callbacks, and the event queue. 

O. USES FOR THE GFX_WORKBUFFER 

.?y"wnp".RMrS^"'^ 5^"^ animation using just the two buffers. However, having the 
GFX_WORKBUFFER as a third provides many more options for assembling complex graphics and 

animations. ' ^ o r 

For example, if you use the animation technique commonly called "dirty rectangles" you will 
need a tiiird buffer. "Dirty rectangles" tracks the smallest rectangles of the screen that truly 
need to be restored, which can drastically reduce the need for memory resources. For instance 
If an icon only moves a few pixels, very little of the screen would need to be restored because 
It remains covered by the new icon. 
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WAV Files 

SGOS offers powerful sound capabilities that are simple to use. 

As you are designing your game, format all of your sounds as wav files and place them in the 
app.temp directory. You will manage all of your game sounds with a few API calls. Playing 
Soimds 

You play the sound file named char* file using the API function 
sound_pl ay(char* file, int channel, int loop, Int pan). 

You can set whether the file loops, pick any of 32 channels, and fade left-right (2 to -2). For 
example, 

sound_pl ay(mysound, 15, 1, -2) 

would set the channel to 15, cause the sound to loop, and pan fully to the left speaker. The 
sound would not stop until you call sound_stop(15). 



NOTE.., Changing modules (inod^exi t, inod_l oad) does not stop the soxmd play. For exam- 
ple, if there is a looping sound playing during the main game play and the bonus is hit, 
when the bonus module is loaded the recurrmg main play sound will need to be manually 
halted with the sound^stop command. 



Changing modules does not stop the sound, i.e., leaving the main play screen with sound play- 
ing and entermg the bonus module would still have the main play sound playing. 

You set the master sound volume with sound.volume(int percent), as a percentage of the 
hardware setting. 

Refer to the complete API lisings in Appendix C for a more complete description of all the 
sound API calls. 
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Chapter 9 - Non-Volatile RAM (nvram) 



A. NVRAM Role in SGOS 



4 



NOTE... Your development computer will use a file in the app. temp directory called nvram 
to represent the target machine's non-volatile RAM. For simplicity, this manual refers to 
both the non-volatile RAM hardware and your development nvram file as "nvram" Most 
references will be to the nvram file, since the manual presents game development concepts 
CAgp/er 2^ discusses Shuffle Master's nvram hardware solution for the target machine 



With SGOS you will use flash memory or other type of non-volatile RAM (nvram) to preserve 
needed game data across executions. SGOS stores two basic types of data in nvram: 

^- Data YOU set for your gamg . You can set up structures and variables as needed to store 
data needed across executions among your game modules. You cannot directiy access 
the nvram, and must use API fimctions to set, get, and modify your game's nvram val- 
ues. 

2- Data the librgry maintains . The nvram stores game history to provide accounting 
records, and tracks "game states" such as INITIALIZE, PUY1, and EVALUATE to tell the 
game engine what it is supposed to be doing and where to resume in case of a power 
failure. 

This chapter covers only the first kind of nvram data and the API functions you will use to 
store data m one module and retrieve it in another. Chapter 11 will cover the crucial game 
state concept and how you work with it in designing a game, 

B. Setup of nvram Data with mygame.state 

Your game application cannot directly touch nvram. The SGOS library includes a special set 
of routines to manage the nvram data as a text file. All game manipulations of the nvram occur 
through these functions. The mygame. state file defines how your game level nvram values will 
be stored. 

You will want to give careful thought to organizing the data you want to store in nvram The 
. state file makes it easy to put variables in the nvram, since the game application never needs 
to be concerned with the offsets of nvram variables. Structure definitions can even be nested. 

You use an nvram string to refer to a specific variable in nvram, for example Game.cred- 
itsleft. You can access arrays with standard printf -style format characters, with values 
inserted as the additional arguments on each Ime. For instance you could write strings such as 

Hlstory[%l].bet, 

Stats. icon[%l], 

or even 

Bi 1 1 Hi story t%l ] . date[%l ] . 

More elaborate formats are also possible, such as MyStruct.Xs[%l], since the string is format- 
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9.C - nvram API Funciions 



9-2 



ted before being parsed. 

The nvram handler partitions nvram into variables, guided by the contents of the raygame state 
file. This text file looks similar to a list of C structure declarations, except that it uses # as the 
comment character to show lines that will not be parsed. For example, the tutorial in Chapter 
20 uses the following code to set up a structure bal I that will hold icon location and velocity 
data for up to fifiy animated balls: 

# Optional comment line 
struct ball { 

int x; 

I nt y; 

i nt x_vel ; 

i nt y^vel ; 

int handler; 

} Ball [50]; 

The library's nvram handler reads and parses this data at startup. The nvram structures are fro- 
zen for a completed and compiled game design. Your game.state file defines the variables on 
the target machme before your program ever runs. Even on your development computer you 
cannot add new variables or change the size of an array while your program is running. 

C. NVRAM API Functions 

Figure 9-1 shows schematically how the nvram API functions communicate between your 



game.$o 



T 



getState 
Functions 



setState 
& 

incState 
Functions 



Non-volatile RAM 



1 See userapl appendix for complete nv_set & nv_get functions. 
2. A development computer simulates nvram with a file named 
nvram in ttie directory user/local/sgos/shared,sfifi. 



Figure 9-1 - Use of nvram with game.so 

game and nvram. 

You input or update nvram variables with the set.state, get.state, and I nc^state functions, 
ihe API mcludes six of each of these functions, one for each variable type: Char Short Int 
Long, Float, and Double. For example, the tutorial in Chapter 20 uses the following function 
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calls to set and retrieve a variable named bal I . x: 
nv.seti nt("Bal I [%d]. x", bal I s[i ]. x J ), and 
nv^geti ntC'Bal I [%d]. x", &bal I s[l ], x, i) 

Refer to Chapter 20 to see the complete example, including the nygarae. state file and example 
game code. Appendix C explains the arguments for each function, 

D. Clearing NV-RAM 

On your development computer, you must clear the nvram to reset it whenever you add or 
remove variables or change the layout of the nvram. To clear the nv-ram on the development 
platform simply delete the nvram file. SGOS will detect the nvram clear and then remitialize it 



E. NVRAM Callbacks 

SGOS provides for "nvram callbacks". Each callback function is associated with an nvram 
variable. When that varable's value is changed, the callback is called. ***Does this just refer to 
the game hooks, or can callbacks be passed with the API functions?*** Elaborate. 



to zeros. 
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Chapter 15 - Building a Game1 
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Chapter 10 - File Structure 



A. File Tree 

Figure 10^1 ~ SGOS File Tree shows most of the SGOS files you will see and work with.] 
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Figure 10-1 - SGOS File Tree 
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B. Required Files 

Table 10-1 describes the key files in your app.temp game directory. 

Table 10-1. Developer Game Files in app.temp Directory 



hite NArVie 

! = Make utility generates 
file 


Tjsscppnsn 


U6iail&! Uhat!>t6i^ & At^f^^rtdik fefe 






vjeneraiSa 
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aeoug.warn 


"T" 


caeneratea 


lexi Tiie or nvram variaoie type aeoug 
errors, Chapter 


Tontnames.ttr 




hont Tiles 


inciuae an rom rues neeaea tor game 


game.staie 




iNivram — game speciTic 
data 




game_DooKs.c 




screen 


<jame dooks screen "winning statisiics"; 
developer provides data 


generic_tempiate.c 




ciame template 




generic_tempiate.n 




uame template 




neipx 




Help screen text, layout 




iastgame_tempiate,c 




Ciame nistory screens 


uame nistory screens & runctions; scroll to 
last and previous games 


locai.oii 




Hardware senings 
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Appendix ; see uukum Tor current Tiie 


start.oti 




Kesource initialization 


unapter ana Appenaix 


iempiate_nistory.c 




baves nistory 


uontains Tunctions to save game nistory 


version 




user s version no. 


user assigns version no. to tracK game 
code updates 


.o ana .so rues 




uompiiea oDjeci rues 


Kiacea in user/iocai/sgos/snarea.smi; rerer 
to Filetree, Fig 
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Chapter 11 - Game States and Managing the 

Game Engine 

A. How THE SGOS Game Engine Runs Your Game 



The SGOS game engine and library run all routine game functions and drive the gaming hard- 
ware. As far as possible, code that could be made common to all games resides in the precom- 
piled SGOS library. Creating a functional game in SGOS has two primary aspects: 

L Develop the game personality using API functions and C programming, 

2. Use game engine hooks to "steer" the actions of the game engine and library. 

This chapter will show you how the game engine drives a game, and how you steer where it's 
going. This steering of the game engine may seem a bit indirect at first. The game engine runs 
the entire game and only offers you a handflil of hooks to guide it. The beauty of this approach 
is that all of your housekeeping and accounting and hardware interface is already done. You 
tell the engine at a few key points how it should incorporate your game personality into its 
grand scheme of safely and securely running the game, 

B, Interface Between Game and Library Layers 

There are three prunary mechanisms that the game and library layers use to pass instructions, 
executions, and results back and forth, as shown in Figure 2, These are the User API, timer 
mechanism, and callback mechanism. 



Tools to Create Event-Driven 
Game Actions: 



Game Layer 



Game-specific code only 



1. 



Userapi.cpp - Embedded O/S calls 




2. 



Timer mechanism - User sets timer to 
a callback. For instance on an 
animation or graphics call, when the 
timer expires the callback is made. 



Largest portion of the SGOS 
Pre-approved library layers 



O/S 



3. 



Callback mechanism - Developer 
codes data-driven game actions by 
tying calls to "data events". For 
example, a change in game data is an 
event; It generates a callback when the 
data is touched. 



Figure 11-1 - Event-Driven Game Actions 
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C. Event Queue 

1. startup and Idle Mode 

SGOS starts up as follows: 

Boot Loader — The boot loader loads everything it is instructed to load, then looks for 
st3rt«cpp» 

start — Start is the "main" executable. It launches the program as follows: 

Initializes operating system tasks 

Parses the . oti file and starts Resource Manager 

Parses game, state file (NV RAM handler) 

Loads game, so (game module) 
Game.so — Begms execution of the game engme logic. 

Idle Mode — Game is now ready and waiting for an "event" to move the game along. 

2. Events 

SGOS is folly event driven. When an event occurs, such as a coin or bill being entered a 
program action or series of actions are set in motion. When the event - the pSm 
action or senes of actions - is completed, the game returns to its idle mode and awS^ 
new event. The callback fonctions and timers which drive the events are discussedTelow 

The game developer can react to or create events from the game side, but all events are 
serviced on the library side of SGOS. . i cvems are 

3. User API 

The game layer and deepest library layers of SGOS cannot directly communicate These 
two layers interact via the userapi. data callbacks, and timer callbacks. Data crbacks L 
timer callbacks will be discussed below. I'liioacKs ana 

4. Callback Functions as Game Hooks 

The game engine offers callback functions as "hooks" into the game. These callbacks let 
the game developer airange the needed game events into a unique new game design AU 

h^^t'T'TT' "T""^' ""'^ be manipulated wi& call- 

backs m the developer's game engine. For instance. 



Insert example from template,c 
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defines a base callback into the game layer. The callback function gives the game devel- 
oper a "placeholder" to readily add game-specific logic to the base game engine. 



D. Timer Callbacks 

Timers are a special API function to place events in the event queue. Both animation and 
sound tasks are carried out with timer callbacks. The timer format is 

start tiiner(long timeout, char*^ callback) 

The timeout period in milliseconds is the time until a callback is placed on the queue. Once on 
the queue it is handled on a first-come, first-served basis. Sequence of timer actions should be 
coordinated to ensure that a needed action is not placed too far down in the queue. Avoid tim- 
ers for mission critical tasks. 

E, Game States AND NVRAM 

As noted above, SGOS stores the "state" of various game aspects after any occurrence of 
events. An event can be any of the following: 

• an action by a player of the game, 

• a subsequent action if the player action causes a chain of events, or 

• an error, 

[Further discussion figures, table, and refer to tutorials] 
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Developer's Game Program 

T T 



game.h 
CALLBACK 
FUNCTIONS 

via game 
engine 



game,h 
calls to 
engine 

e.g. 
get_bet 



1 



Engine 
calls to 
game 
e.g. 
begin^play 



SGOS Game Engine 



Internal 
SGOS 



API calls to 
library, with 
callbacks to 
game via 
NVRAM 
or timers 

e.g- 

start_tlmer 



API 
CALLBACK 
FUNCTiONS 

no access 
to engine 



SGOS Library 



Figure 11-2 - API Calls and Callbacks to Game 



1 1 shows the five key game states that drive a typical game, and Usts the primary callback 
Table 11-1. SGOS Primary Game States and CaUback Functions 



PRIMARY 
GAME STATES 


GAME ENGINE 
CALLBACK FUNCTIONS 


NEXT STATE 
SET BY 


Game is always be in one of 
these basic states. 


Hooks from the game into the 
game engine. 


/Wosf set by 

game engine 



r» / shuffle A/la<;<-^ r 
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Table SGOS Primary Game States and Callback Functions 



1 Initialization 

1 Start up or reset game 


init_game 

reset_game 

cache_gfx 

draw_game_screen 

enable_max_bet 

disable_max_bet 


SGOS 
Engine 


1 IDLE 

jGame up and ready for play 


attract 

animatejdie 


SGOS 

Engine 1 


1 BEGINPLAY 

1 Initiate with coins or other cred- 
1 its 


begin_play 
maxbet_game 
pick_numbers 
updatejights 

UDdate buttnnQ 


SGOS 1 
Engine 1 


1 PLAY1 

1 First play sequence 


play_one 

updatejights 

update_buttons 


Game 1 


1 PLAY2 

1 Subsequent play sequence 


play_two 

updatejights 

update_buttons 


Game 1 


1 EVALUATE 

1 Evaluate for win or bonus 
1 4A. BONUS 
1 48. JACKPOT 


c?vaiudi6 game 

checkjorjackpot 

checkJor_bonus 

bonus 

animate_winner 
award_sound 
updatejights 
update_buttons 


SGOS 1 
Engine 1 


1 FINISH 

1 Payouts and bookkeeping 


finish_game 

updatejights 

update_buttons 


SGOS 1 
Engine 1 


Note: The above callback functions are hooks Into the SGOS game enaine and III 
toTov^1h^TJ°^,'r,%^^^^^^ endpSesTeclSbaoi 
\ camok%%Sti%"^^^^^^ developer creates a new game personality 


^ra/y. The game 1 
<s as appropriate 1 
^ defining how the 1 



- ..W.I.XX, x^ujiiciuus uuicr gaiiDacK runctions are available 

tor game design, but the game engine looks for these primary callback functions to advance 
through a game. 

The erigine includes twenty-two states, many of which you will not see at the game layer. The 
followmg is a complete list of SGOS game states, as defined in gamestate. h: 
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IDLE 

BEGINPLAY 

PLAYl 

PLAY2 

EVALUATE 

FINISH 

CREDITSIN (no game-specific aspects) 
COUNTDONN (no game-specific aspects) 
JACKPOT (no game-specific aspects) 
HANDPAY (no game-specific aspects) 
SETUP ( no game-specific aspects) 
PAYOUT (no game-specific aspects) 
BETTING (no game-specific aspects) 
BONUS 

BONUSCOUNT (no game-specific aspects) 
MAINMENU (no game-specific aspects) 
AUTHORIZE ( no game-specific aspects) 
COUNTDOWNHOPPER (no game-specific aspects) 
TEST (no game-specific aspects) 
HOPPERTEST (no game-specific aspects) 
BILLTEST (no game-specific aspects) 
ATTRACT 
***update this list*** 

R Schematic of Game State Progression 

Add discusssion and also update Figure 11-3 
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IDLE 






> 


f 






If award or pay 




animate winner( ) 










1 


> 


f 






If credits = 


cashjimit 




PAYOUT 












if 6 mins no credits and 


— ^ 


ATTRACT 


not touched 





ATTRACT 



attractO 



changes game state back 
to IDLE 



INITIALIZE 1 



If Ram Test = clear 



init_game{ ) 



cach_gfx( ) 



draw_game_screen( ) 



an!matejdle( ) 



updatejights( ) 



check_for_bonus( ) 



if bonus 



if win 



reset_game( ) 



resetjgame_history 



LEGEND : 

BOLDCAPS = game state 
UNBOLDCAPS = game state ref. 
lower_case( ) = function 

callbacks/hooks to engine 
plain lower case = test or comment 
T « TRUE 

NOTES : 

1 . If the provided SGOS templates are 
used, the game code must use the state 
machine and related game hooks, 

2. The generic, 9 line, and poker 
templates in SGOS V 2.0 use the states 
and hooks shown. 



bonus_complete( ) 



anlmate_winner( ) 



Figure 11-3 - State Machine and Related Game Hooks 
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BEGIN PLAY 



pick_numbers( ) 



begin J3lay( ) 



PLAY1 



EVALUATE T 



evaluate_game( ) 



check_for_bonus( ) 



if no award and no bonus 



if award 



*PLAY1 



playlO 



game sets state to PLAY2 



FINISH 



animate_wjnner( ) 



check^forjackpot 



if jackpot 



if bonus 



BONUS 



if award > handpay 



HANDPAY 



COUNTDOWN 



PLAY2 



Play2() 



game sets state to 
EVALUATE 



JACKPOT 



Figure 11-3. State Machine and Related Game Hooks — Continued 
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JACKPOT 




casino operator must 
reset with key 





BONUS t — ^ 



bonusO 



HANDPAY ~1 — '-^ 



FINISH 



PAYOUT 


T ^ 


FINISH 


> 












1 COUNTDOWN 


1 
1 






\ 


f 








if credit + award 


T ^ 


if award 


> credit limit 


: ^ 


<cashout limit 










f 








HANDPAY 




f 








if snap 


T ^ 


play snap.wav 


. — ^ 












\ 


f 








FINISH 


















FINISH 




CREDITS JN 




f 






f 


save_game_history( ) 




play credit. wav 


> 


f 




> 


r 


updatejights( ) 




updateJightsO 




f 








anfmatejdle( ) 




if credits = 


cash limit 












> 


f 






f 


finfshjgame( ) 




IDLE 



COUNTDOWN 
HOPPER 



PAYOUT 



J 



Figure 11-3. State Machine and Related .Game Hooks - Continued 
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Chapter 12 — Initialization (.oti) File 

A. Basic Settings 

B. Don's New Section 
C- Etc. 
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Chapter 13 — Multigame Setup 



A. Multigame Considerations 

game_register 

game_load 

game_inprogress 

game getcurrentstate 

game_setcurrentstate 

game_setdenomination 

B. Naming of Files 
C- -OTi Initialization 
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Chapter 14 — Game Development Tools 



A. C Compiler 

Different compilers may use different instructions. To ensure consistency with SGOS and the 
Makefiles, stick with the popular gcc C compiler. A copy is included with SGOS. 

B. Makefile 

The fflake tool and related llakef i I e will be familiar to Linux and UNIX users, nake is a very 
powerful way to manage and update your game projects. The llakef i I e tells make how to set up 
dependencies and compile your files. Once you set up the llakefi te for a project you can 
quickly recompile and retest your program as you make modifications. 

Appendix B explains more about how to set up your llakefi i e, and provides an example which 
covers the basics you need to build a game in SGOS. However, the appendix only scratches 
the surface of a tremendously powerful tool, and you may want to use additional features. If 
you do not akeady have one, a good Linux programming book is highly recommended. 

If you are new to make and the llakefi I e, the tutorial examples will provide good practice in 
using them to build simple games. File Listing 16-2 in the first tutorial chapter starts you out 
with a makef i I e for a single file "game" that simply draws a "Hello World" text string. In the 
five tutorial chapters that follow you use the makefile several more times to add graphics and 
other files. 

C. Creation of Reel Strips Tool 

The Makestrips utility will turn a list of par-sheet (tab-delimited text) files into C source code 
arrays. This Python Script tool is listed and documented in Appendix H, The file is included on 
the SGOS CD-ROM, Once you see how Makestrips works, you might prefer to devise your 
own tool to set up reel strips. 

D. Graphics Conversion Tool 

You may have numerous graphics files for your game, especially if you have complex anima- 
tions. Your game must include each graphic icon as an array in XPM format. The included 
Python Script tool convgfx. py provides a simple way convert your graphics all at once and 
place them into one graphic icon file. Help in using this tool and further organizing your icons 
can be found in the following places in this manual: 

• Chapter 7 tells how to use convgfx. py and suggests ways to further arrange your icons. 

• Chapter 1 7 includes a simple example that converts a single icon to an XPM array. 

• Chapter G provides a file listing of convgfx. py. 

As with the other SGOS tools, you may want to create a graphics conversion tool of your own 
that best suits your design approach. 
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E. Debugging Tools 

1. gbd Linux Tool 

gbd is a popular and powerful Linux tool. It is highly recommended 

2. sys_debug() 

sysJebugO is an API call included with SGOS that allows you to put debug statements in 
your code, and they will be included in debug, out. ***is name changed?*** 

You set debug preferences in the .oti file as follows: 
debug : { 

output : file; 
options : {al I ;} 

} 

In tMs example all will yield copious results for all declared variables. **What are other .oti 
options?*** 

You use printf-style formatting to call out each occurrence you want to see in the debug, out 
file with 

vol d sys_debug(char* format, , . . ) . 
You pass a format string followed by variables, if any. 

The tutorial in *** gives a helpful example that sets up debug items with extra formatting to 
help certain timer actions stand out in the generated debug, out file. 

3. debug.warn and dbug.out 

On your development computer (but not on a target machine) SGOS creates debug, out and 
debug, warn in the current directory. They are log files created if the game is run with a library 
compile with the debug option turned on. 

debug.warn will let you know of any type mismatches getting or setting variables in nvram, 
such as passing a character to a variable set as an integer. 

debug, out provides a text file of results (e.g. gets and sets from RAM, all events on queue, 
etc.) for the options set by the user. Programmer can set the level of debug output. 
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Chapter 15 - Building a Game 



A. Building a Game on Development Platform 

make. Makefile, etc 

B. Testing Considerations 

maybe not 

C. Building a Game on a Target Machine 

Ref Ch XX hdwr sorn 
Gen notes 
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IV. API TUTORIAL 

Chapter 16 - Displaying Text 
Ctiapter 17- Drawing an Icon 
Chapter 18 - Using the Frame Buffer and Timers 
Chapter 19 - Adding Buttons 
Chapter 20 - Using Timers to Move an Icon 
Chapter 21 - Tutorial: Using Nvram 
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Chapter 16 — Displaying Text 



A- Overview 

This chapter creates a simple "Hello World" program using SGOS library calls. The tutorial 
will include the following SGOS tools and concepts: 

• Using SGOS API calls 

• Building an operable "game" with the Linux make utility 

• A few basic guidelines about managing files for an SGOS game 

B. Assemble Needed Files to Run SGOS 

In your installed sgos directory, create a directory named app. tutori al with the nkdi r com- 
mand: 

[sgos]$ nkdir app. tutorial 



TIP..- Refer to Chapter File Tree and Figure 10-1 - SGOS File Tree to see how 

directories and files are arranged in SGOS. ///. GAME DEVELOPMENT cover com- 
plete file setup requirements for a game. 



To successfiilly run the example you will need to include several files in your new directory. 
The following files must be in [your patli]/sgos/app. tutori ai for Example 1: 



1. 


Uakef i 1 e 


used to build the game 


2. 


examplel.c 


the Hello World file you just created 


3. 


game. state 


used here only to launch SGOS 


4. 


impact. ttf 


truetype font 


5. 


local .oti 


configuration file for running SGOS on your desktop computer 



Locate these files (again refer to the file tree) and copy them to your new app. tutori al direc- 
tory. 




WARNING! Note that I ocal . oti replaces start, oti for your desktop development com- 
^ puter. I ocal .oti disables hardware such as the bill handler and coin hopper. If they are not 
: disabled your computer may crash when the program looks for them. 



C- Using gfx Functions From the userapi 

This first example is a very simple "Hello World" screen. The code should look familiar if you 
are an experienced C programmer. 

You will need exampf e1. c as shown in File Listing 16-1. Copy it fi^om the CD-ROM to your 
app. temp directory, or type it in directly using any text editor. 

Line 1 includes the header file userapi .h, which defines all of basic API functions needed for 
SGOS progranmiing. Chapter 5 provides an overview of the available routines. Appendix C 
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File Listing 16-1: examplel.c 

1 #include "userapi.h" 

2 void initial ize(void){ 

3 gfx_clearscr(0); 

4 gf x__setf ont ( " \ mpact , ttf " , 72) ; 

5 gfxjrawstri ng(100, 100, "Hal I o Worl d", RGB(255, 255, 255), -1); 

6 } 

This file is included in the SGOS installation CD-ROM tutorial directory. 
gives a complete listing with explanations. 

The remaining code in examp! el . c defines i ni ti al i ze(), which is the first function the game 
engine will call after loading the module. The gfx functions are API routines, used as follows: 

Lines gfx_clearscr( ) clears the screen bufifer to white- Note that 0 is equivalent to 
RGB(0, 0, 0) in the RGB color convention. 

Une 4 gfx_setfont( ) sets the current truetype font and point size. Each font you specify 
must be in your program's directory. The font and point size will stay the same 
until you change it with another gfx_setfont( ). 

Line 5 gfx_drawscreen( ) puts the string "Hello World" on the screen buffer. 

100, 100 locates the lower left comer of the string at (x, y) = (100, 100) on the 800 
X 600 pixel screen. 

RGB(255,255,255) defines black as the font color. RGB(r,g,b) is a macro function 
in the SGOS library. 



TIP... The last parameter of gfx_drawscreen() is an RGB background color. -1 is 
shorthand which SGOS converts to a transparency. Likewise, 0 is shorthand for 
RGB(0, 0, 0), which is white. 



Chapter l-G, Colors Reserved for Transparency explains how SGOS handles RGB colors and 
transparency. 

D. Using Make and the Makefile 

If you are new to Linux, you will soon find that the make utility is a powerful tool to build, 
compile, and manage your programs as you develop them. Chapter 14-B, Makefile provides an 
overview, and you can learn more about make in a Linux programmmg book. 

1 • Creating the Makefile for examplel x 

File Listing 16-2 shows the generic Ifakefi le you will need to create projects for all the 
tutorial examples. You can copy this tutorial version of llakefi le from the tutorial direc- 
tory of the CD-ROM app. temp diectory or type it fi-om scratch using any text editor. 

Note that lines 13 and 14 of llakefi le refer to examplel . o, the object file you will create 
for the Hello World example. For the other tutorial examples, you will change these lines 
to exampl e2. o, etc. and add any other needed files before you build the example game. 

Refer to the Makefile listing in Appendix B for a review of sjmtax and dependency rules. 
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File Listing 16-2: Makefile for examplel.c 



1 


?F maKcl 1 1 G lOr Lne cXainpt CS 


o 

c. 


. ourr 1 Auo. . ^pp • ^ • 


3 

o 


DEBUG- -n 


4 




5 


INCLUDE=-1.. -I$(SG0S) 


6 


.c.o: 


7 


gcc $(INCLUDE) -c -Wall -fPIC -o $@ $< 


8 


. cpp, o: 


9 


g++ $(INCLUDE) $ (DEBUG) -c -o $@ $< 


10 


.o.so: 


11 


gcc -shared -o $@ $< 


12 


a! i : game. so 


13 


game. so: examplel.o 


14 


gcc -shared -o game. so examplel.o 



This file is included in the SGOS installation CD-ROM tutorial file. 



Line 1 3 game, so: exampi el . o says that game, so is dependent on exampi el . o. 

Line 14 gcc -shared -o game. so examplel.o is a command to make a shared object 
out of exampi el . o and name it game. so. 

When make looks at this Makef i I e, it will first try to make al L It will next look at the rule 
for ai I and see that it first needs to make game. so. Further rules tell Hake that it needs 
exampi el . o, and to make exampi el . o out of exampi el . c. The final result is a new game. so. 

2. Compiling the Heflo World Program 

To run the program you must first compile it using make. The build process is as follows: 
[app, tutor! al ]# make 

gcc -I.. -I , ./framework -c -Wall -fPIC -o test.o test.c 
gcc -shared -o game. so test.o 

As noted above, the program will be compiled as a shared object file named game. so. If 
you are new to Linux, the shared object file is analogous to a Windows dl I file. When the 
module loads, the first fimction it will execute is i ni ti at I ze(), 

E. Running the Program 

To run exampi el. so, you must invoke SGOS by running start; start then loads the shared 
object file game, so to run the game. The game will call the function i ni ti al I ze(), which you 
defined in exampi el . c. 

To run start you must be the "super user" (a Linux term meaning you have access to the root 
directory). If you are not logged in as root, type su and the password to become root. Then run 
the program as follows: 

[app. tutor! al ] # /usr/i ocal /sgos/engi ne. shf I /start 
[svgalib: allocated virtual console #8] 
Starting: display modules timer 
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You should see the following screen displays: 

1, Blank screen. 

2. SGOS startup screen, 

3. Background comes up transparent, from your gfx_drawstri ng parameter of -1, 

4, The words "Hello World" will appear in black, as shown in Figure 16-1. 



Figure 16-1 - Tutorial: Hello World Screen 

Press q to quit the program. 

F. Exercises 

You may want to make some changes to some of the parameters in this simple file to observe 
the response: 

1 . Change the font (you should have georgi a. ttf in your app. temp directory). 

2. Change the font size and color. 

3. Change the color of the screen buffer by changing 0 to an RG&() value. 

4. Replace the -1 transparency with an RG6() value. 

5. Move the text around. 

6. Center the text on the screen buffer by replacing gfx_drawstr i ng() with 
gfxj usti fystri ng(0, 0, 800, 600, "Hel I o Worl d", 0, JUSTI FY_CENTER, -1) . 

You can also add a new line character with gfxjustifystringO, for instance 
"*Hel I oXnWorl d", which gfx_drawstri ng() does not support. 




Screer colors are 
changed for foadobility. 
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Chapter 17 — Drawing an Icon 



A. Overview 

This chapter puts a simple graphic icon into the source file and then draws it on the screen. The 
tutorial will include the following SGOS tools and concepts: 

• Graphics conversion tool and XPM format 

• SGOS transparency 

• Further examples of SGOS gf x functions and using the Makefile 

B. Converting a Graphic to XPM Format 

You must convert all graphics to the special bitmapped XPM format to display them in SGOS, 
Chapter 7 gives details about the conversion tool and how SGOS handles graphics. Copy the 
file bal I . ti f from the CD-ROM into your app. tutor i al directory, and use the Python script 
conversion tool convgfx. py as follows: 

[app. tutorial]* ./convgfx.py ball_gfx 

Running the script creates the C++ file bal I _gfx. cpp and the header file bal I x. h. File List- 
ing 17-1 shows how the XPM format maps out the graphic of the ball as the array const char* 
const bal I [], In this case it is easy to see the shape of the ball since the graphic has only two 
colors, represented by the hex characters . and 9. Although it looks egg-shaped as represented 
by the characters, it will be round when the actual pixels show up on the screen, 

convgfx. py defines each graphic array as the name of the file it came from, except that the file 
suffix, in this case . ti f , is dropped. As a result this graphic array is named bal I . convgfx. py 
is fully listed in Appendix G. You can modify it or write your own script if you like, as long 
you generate the needed , c and . h files. 

C. Using SGOS gfx Functions to Display a Graphic 

You can copy File Listing 17-2 from the SGOS CD-ROM app. temp directory or type it 
directly. 

This file looks like exampl el , c, except that you must add the bal I _gfx, h header file to include 
the bal I graphic, and use different SGOS graphics functions as appropriate to display the icon- 
Only lines 2, 5, and 6 have changed, with the following effects: 

Ln 1-2 Again include userapi , h, plus the file bal I _gfx. h. created by the graphic conver- 
sion tool. The header file simply tells the compiler there is a graphic named bal I . 

Line 3 Again, i ni ti al i ze() will be the first fimction executed upon loading. 

Line 4 gfx_cl earscr( ) clears the screen to black, 0 is equivalent to RGB(0, 0, 0) 

Line 5 gfx_drawi conXPII() puts the graphic onto the screen. SGOS calls graphics "icons/' 
hence the name drawi conXPii for the function that draws a graphic of type XPM 
created by convgfx. py. The number pair are the coordinates of the upper left comer 
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File Listing 17-1: balLgfx-cpp 

1 #include "ban_gfx.h" 

2 const char* const bal I [] = { 

3 /* width height num.colors chars^ier^pi xel */ 

4 " 50 50 2 1", 

5 /* colors •/ 

6 c #O0aaOO'\ 

7 "9 c #ffOOff". 

8 /♦ pixels V 

"99999999999999999999999999999 999999999999999999999' 
"99999999999999999999999999999999999999999999999999* 
"99999999999999999999999999999999999999999999999999 • 

"99999999999999999 99999999999999999999' 

"99999999999999 999999999999999999' 

"999999999999 99999999999999999* 

"99999999999 999999999999999' 

"9999999999 99999999999999" 

"999999999 9999999999999*' 

"99999999 9999 99999999" 

"9999999 99999999999" 

"999999 9999999999.1 

"99999 999999999" 

"99999 999999999 " 

"9999 99999999 11 

"9999 99999999 " 

"999 9999999'* 

"999 9999999" 

"999 9999999 " 

[conti nued, for the bottoa hal f of the ball . . . ] 

_h 

Code shown at reduced size to show use of 9 as transparency. 



File Listing 17-2: example2.c 



1 #i nc! ude "userapi . h" 

2 #include "bal l_gfx.h" 

3 void initialize(void) { 

4 gfx_clearscr(0); 

5 gfxjrawi conXPM(200, 200, (char**) bal I ); 

6 gfx_draw3dbar (100, 100, 200, 200, -1 , RGB(0, 0, 100) , RGB(100, 0, 0) , 5) ; 

7 } 

This file is included in the SGOS installation CD-ROM tutorial file, 

of the graphic. The SGOS function gfx^drawi conXPM() typecasts bal I so it will be 
passed correctly, since it is defined as a constant. The graphic in the file 
bal l^gfx.cpp will be joined with this file at link time. The graphic is simply an 

array of strings as you saw in File Listing 17-1, 

Line 6 gfx__draw3dbar(100, 100, 200, 200, -1, RGB(0, 0, 100), RGB(100, 0, 0), 5) draws a blue 
and red box. 
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D. Revise Makefile 

You also need to change the Makefile as shown in File Listing 17-3 to define the dependency 
of show_bal I . o on the file bal I _gfx, o. 

File Listing 17«3: Makefile for example2,c 

1 # Makef i I e for the exampi es 

2 .SUFFIXES: .cpp .c ,so 

3 DEBUG=-g 

4 SGOS=:${shel I . /I ocate sgos} 

5 INCLUDE=-I.. -I$(SG0S) 

6 .c.o: 

7 gcc $(INCLUDE) >c -Wall -fPIC -o $@ $< 

8 .cpp. o: 

9 g++ $( INCLUDE) $ (DEBUG) -c -o $@ $< 

10 .0. so: 

11 gcc -shared -o $@ $< 

12 ail: game. so 

13 game. so: exampi e2.o ball _gfx.o 

14 gcc -shared -o game, so exampi e2.o ball^ gfx. o 

This file is included in the SGOS installation CD-ROM tutorial file. 

Lines 1 though 12 are unchanged. 

Ln 13-14 game, so: exampleZ.o ba!l_gfx.o tells make that the shared object, game.so, 
depends on these two files. Also, you add bal l_gfx.o to the gcc compile instruc- 
tions. 

E. Running the Program 

You will see the same SGOS startup screen displays as in the previous example. Then you 
should see the ball as shown in Figure 1 7-1, below. Press q to quit. 




Figure 17-1 - Tutorial: Ball Icon Screen Display 
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R Change the gfx Function to Make Transparency Work Correctly 

The ball showed up with a bright magenta icon background, because the character 9 in file 
baf l^fx.cpp denotes RGB(255, 0,255), pure magenta. The convgfx.py conversion tool con- 
verted the tiff transparent pixels to this color. You can tell' the API you want a transparency by 
using a graphics function that supports transparency. Replace gfx„drawl conXPIlO with 
gfx_drawtransXPII() as follows: 

gfx_drawtransXPy(2Q0, 200, (char**)bal I , "9") 

Make this change in your exampi e2. c code and then rebuild and run the program. The "trans- 
parency'' created by gfx_drawtransXPII() actually retrieves pixels as needed from SGOS's lat- 
est background screen, to effectively create a transparency. Generally, the background screen 
must be updated for this to work. In this simple example it looked transparent because the 
screen was still a default black. The next example in Chapter 18 will show how to update the 
background screen and introduce other transparency options. 

G. Exercises 

Try these or other changes to the exampi e2. c file: 

1. Notice what happens if you change the screen color by passing a different RGB value 
to gfx_clearscr(), e.g. RGB(255, 100, 100). A black box will appear around the ball. It 
did not show up before since the screen was black. The frame buffer causes this, and 
the next chapter will show you more about some important nuances of screen buffer- 
ing. 

2. Try converting other graphics and showing them. 

3. Include more than one graphic file, and show multiple graphics at once. 
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Chapter 18 — Using the Frame Buffer and Timers 

A. Overview 



This chapter uses the ofF-screen frame buffer and introduces timers. The tutorial will include 
the following SGOS tools and concepts: 

• Copying the screen buffer to the frame buffer 

• Using timers and callback functions for animation 

• Role of the event queue 

• Example of interaction among nested timers 

B. Using the Off-Screen Frame Buffer and Timers 

1. Updating the Off-Screen Frame Buffer 

The examples so far have drawn directly to the screen buffer. This chapter will show how 
to use the ofF-screen frame buffer. The API graphic routines that update and use the frame 
buffer are at the heart of SGOS animations. This chapter will use gfx_copybuffer() to 
update the frame buffer (also called the "background"), and it will use 
gfx„copybufferpartO to erase things from the screen buffer. 

Recall in the previous tutorial example that gfx_drawtransXPII() "accidentally" made a 
correct transparency, only because the default all-black frame buffer happened to match 
the all-black screen buffer. In this chapter the background will be multicolored, so 
gfx_copybuffer() is needed to update the frame buffer. 

Chapter 7 gives details about how SGOS uses the frame buffer for transparency and 
screen updates. Appendix C lists and describes the API functions. 

2. Using Timers for Animation 

SGOS event-driven programming makes extensive use oF timers. With every event on its 
own timer you can easii}^ add and remove items from the screen. Also, by using functions 
which call themselves back via timers, you can start animations once and not have to 
worry about them again. 

Chapter 18 explains how timers work and their key role in SGOS programming. Basi- 
cally, a timer is a request to call a function at a certain time. When the timer expires, the 
request to execute its function is placed on the SGOS event queue. If there are already 
many functions on the queue or if an executing function is already running, the call to your 
function will be delayed. So, the actual duration of a timer is only approximate. 

A timer is good for only one call. If you want a function to be called repeatedly, you can 
start as many timers as you need or have the function start a timer to itself before it is done 
executing, 

A timer starts with the API call to timer_start(). You specify a time delay in millisec- 
onds and a function name (not a pointer). For example, timer_start(100, "drawLScreen") 
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tells the API to execute the function draw_screen() in 0.1 seconds. Note that the name of 
the function is used, and not a pointer. The function is not called with any parameters, so 
you would declare draw_screen as voi d draw_screen(vo! d) . 

Multiple occurrences of a timer can call the same function multiple times. For instance, 

timer_start(100, "drawLScreen"); 
ti ner_start(200, "draw^screen"); 

will call draw_screen() in 0.1 and 0.2 seconds from now. SGOS has a system limit of 60 
timers at any one time. This should not limit your options because calls spend little time in 
the event queue. The limit is in place because more than 60 timers could create a bottle- 
neck on a typical processor for a target machine. 



C. Writing the Program 

Copy exampi e3, c from the CD-ROM into your app. tutor! al directory. It should look like File 
Listing 18-L 

This example will give you a good taste of several timers going on at once. Timers and their 
callback functions are a crucial part of SGOS programming. Once you get used to them, you 
will find they often simplify your code requirements. Rather than having to tightly control 
when everything happens, you can launch several different types of actions with no worry they 
will collide. Each timer will launch its callback function when it comes up the event queue. It 
does not care what the other callbacks are doing — even if another function fails, it will keep 
going! 

Tutorial exampi e3. c uses timers, for loops, and a clever incrementing of colors to make a lot 
happen on the screen. You may want to make various changes to the timers and gf x functions 
to see the effects. 

Ln 1-2 Include userapi . h and bal i _gfx. h graphic. Leave the ball in the program, since the 
next program, which builds on this one, will use it. 

Ln 3-8 Define several colors and dimensions. 

Ln 9-13 Declare several prototypes: draw__screen() draws the checkered screen; counter (), 
f I asherO, bl t nker () and bl i nker2() are the timer callback functions. 

Ln 14-15 count and fiash are global variables used by counter() and fiasher(), respec- 
tively. 

Ln 16-22 i ni ti al i ze() first draws the screen, then continues with these steps: 

Copies the screen buffer into the frame buffer with a call to gfx_copybuffer(). 
Initializes the global variables 

Starts two timers, one to call counter () in 0.1 seconds and one to call f I asher() in 
0.75 seconds. 

Ln 23-34 draw_screen() first clears the screen buffer to black, then fills in the entire screen 
buffer with a grid of boxes, using two for loops, below. 

ROT_COLOR cycles through some colors by incrementing the color integers. 



Ln 35-38 The counter () function performs the following: 
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File Listing 18-1: exampleSx 



1 #i ncl ude "userapi . h" 

2 #i ncl ude "ball_gfx.h" 



3 
4 



#def i ne COUNTERJOLOR 
#define FLASHER_COLOR 



RGB (255, 0,0) 
RGB(0,0,0) 



5 
6 



#define SCREEN_WIDTH 
#define SCREEOEIGHT 



800 
600 



7 
8 



#deflne BASE^COLOR 
#define R0T_COLOR(a) 



Oxidab 

(((a«l) + (a»14)) & Ox7fff) 



9 void draw_screen(voi d); 

10 void counter (void); 

11 void flasher (void); 

12 void bl inker (void); 

13 void bl i nker2(void); 

14 int count; 

15 int flash; 

16 void initial i2e(void) { 

17 draw_screen(); 

18 gfx_copybuf fer(GFX_SCREENBUFFER, GFX_BACKGROUNDBUFFER) ; 

19 count = 0; 

20 f I ash = 0; 

21 ti mer_start(100, "counter"); 

22 ti mer_start(750, "f I asher") ; 
} 

23 void draw„screen(void) { 

24 int x,y; 

25 int color; 

26 gfx_clearscr(RGB(0,0,0)); 

27 color = BASE_C0L0R; 

28 for (y=0; y<=SCREEN_HEl GHT-50; y+=50) { 

29 for(x=0; x<=SCREEN_WI DTH-50; x+=50){ 

30 gfxjrawbar (x, y, 50, 50, col or) ; 

31 color = R0T_C0L0R(color); 



37 gfx_setfont("georgi a. ttf 36) ; 
38 

gfx„copybufferpart(100, 100, 200, 50, 100, 100, GFX.BACKGROUNDBUFFER, GFX^SC 
REENBUFFER); 

39 gfxj usti fystri ng(100, 100, 200, 50, i decl (count, 4) , COUNTER.COLOR, 

40 JUSTIFY„CENTER, -1); 

41 ti nier_start(100, "counter"); 



32 
33 
34 
35 
36 



} 

} 

} 

void counter (void) { 
count++; 



42 
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File Listing 18-1: exampieS.c (continued) 



43 


void f 1 asher(voi d) { 


44 


flasn =: 1 - flash;/* toggle flash */ 


45 


if(flash){ 


46 


gf x_setf ont ( " i mpact . ttf " , 72) ; 


47 


gfxj usti fystri ng(0, 300, 800, 300, "FLASH! ", FLASHER COLOR, 


48 


JUSTI FY JENTER, -1); 


49 


ti mer_start(50, bl i nker ); 


50 


}el set 


o 1 






grx_copyDurterpart(0, 300, 800, 300, 0, 300, GFX JACKGROUNDBUFFER, GFX_SCREE 




nBUFFER) ; 


52 


} 


53 


timer^start(750, "fl asher"); 


54 


} 


55 


void bl i nker(voi d) { 


Ob 


1 tcti asn; 1 


57 


gfx_drawtransXPM(525, 175, (char**)bal 1 , "99"); 


58 


timer start(50, "bl inker2"); 


59 


} 


60 


} 


61 


void blinker2(void) { 


62 






gfx_copybufferpart(525, 175, 50, 50, 525, 175, GFX BACKGROUNDBUFFER, GFX SCR 




EENBUFFER); 


63 


ti mer start (50, "bl i nker"); 


64 


} 



This file is included in the SGOS installation CD-ROM tutorial file. 



Increments the global variable count 
Sets the current font to 36-point Georgia. 

Enlists gfx^copybufferpartO to copy a rectangle from the frame buffer to the 
screen buffer The first four arguments define a rectangle in the frame buffer' by 
specifying top left comer, width and height. The next two arguments locate the 
rectangle on the screen, based on the top left comer of the rectangle, and the last 
two note the source and destination buffers. 

Ln 39-40 gfxJ usti fystri ng() displays the count on the screen, i deci () is a utility function 
in userapi . h that converts an integer to a string. The 4 argument to i deci () is the 
number of digits from the least significant digit to display (e.g. 23456 would be 
displayed as 3456). It passes back a char pointer to a global buffer which is valid 
until the next call to i deci (). gfxJ usti fystri ng() is first given a rectangle (as top 
left comer, width and height), the string to display (given by ideci ()), the text 
color, the justification of the string in the box (in this case it is centered both verti- 
cally and horizontally), and finally the background color, which is -1 for transpar- 
ent 

Line 41 Finally, counter () starts another timer to call itself back just before it exits, 

Ln 43-54 The flasher() function is similar to counter. It first toggles its global variable 
which tells whether f I asher () is flashing on or flashing off. 
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If it is flashing on, it sets the font to 72-point Impact and draws its string centered 
in the bottom of the screen. It then starts a timer to bl i nker(). 

Otherwise, flasher () erases the text from the screen buffer with a call to 
gf x_copybuf f erpart () . 

In either case, it then starts a timer to call itself back. 

Ln 55-60 The bl i nker() function first checks to see if f I asher is on or off by checking the 
global variable flash. If flasher() has displayed text, bi inker () draws the bail 
icon and then starts a timer to call bi i nker2(). 

Ln 61-64 The bl i nker2() function erases the ball icon by copying the corresponding rectan- 
gle from the frame buffer, and if flasher() is still displaying flash, starts a timer 
to call blinker (). 

D. IVIiNOR Changes to Makefile and Compile 

Make and compile the program. Change the filename to example3.c. Otherwise this will just 
be a simple update with no new directives. Although this program does not use the ball graph- 
ics, leave the ball in the program since the next example will use it, 

E. Run the Program 

Run the program the same as in the previous examples. After the startup screen you should see 
the screen filled with a checkered pattern, and the text animations should flash and count, as 
shown in Figure 18-1. 

Unlike the two previous examples, which gave static screen results, examples. c will keep 
blinking and flashing xmtil you quit. 

Press q to quit 

F. Exercises 

Make these adjustments and any others that look interestmg. See how your program responds: 

L change f I asher () so that it is on the screen for .75 seconds and off for .5 seconds. 

2. add a function called mover () which moves a ball across the screen. Have it cued to 

begin when count— 300. Have it end when count==500. Continue in this way; turn on 

when count%300:==0, turn off when count%300==200. 
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Figure 18-1 - Tutorial: Frame Buffer with Counter 

The next tutorial example will add buttons to launch an animation and modify its mission 
while it runs. 
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Chapter 19 — Adding Buttons 



A. Overview 

This chapter adds buttons and other new features to exaopi e4. c from Chapter 20, to give you 
practice with additional SGOS functions and design approaches. The tutorial will include the 
following SGOS tools and concepts: 

• Add buttons for on/off and reset actions 

• Add sound 

• Add a ball direction component to show further button and timer nuances 

• Use the frame buffer differently to reduce flicker 

B. Using SGOS Buttons 

In this chapter you will add several buttons to launch or modify program actions. The three 
SGOS button types and "hot spot" routine all work in the same way. The example will use the 
simplest button type, which contains a simple text string. To learn more about the role of but- 
tons and their API routines, refer to Chapter Button Events and Appendix C 

If the target machine will have mechanical buttons, they can make calls to the same functions. 
You define hardware lights and switches (panel layout) in the initialization file start, oti . See 
Appendix D for details. 



WARNING! Do not put buttons in the off-screen fi'ame buffer. As a general rule, make 
Jt?;" sure that you add buttons to the screen buffer after you use gfx_copybuffer(). If you copy 
a button from the background to the screen you may get a picture of a button with no func- 
tionality. 



C. Writing the Program 

Copy exampl eS. c into your app. tutori al directory. It should look like File Listing 19-L 

This example builds on the previous tutorial in Chapter 20, Some of the previous routines are 
divided into several more functions so each can be distinctly called. The three buttons you add 
will start, stop, or reset the balls. 

First, a brief overview of what the exainpl e5. c program does: 

1 . Builds the checkered screen with buttons. 
2- When player presses "Go'' button: 

a. Starts timer with callback to animate the balls 

b. Plays a button sound 

c. Keeps animation routine going with a timer and callback to itself 

d. Due to the "gravity" function, balls gradually collect at bottom of screen 
3. When player presses STOP! button: 

a. Kills all timers, which stops all balls 

b. Plays a button sound 
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1 

2 

3 
4 

5 
6 

7 
8 

9 
10 

11 
12 
13 
14 

15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 

28 
29 

30 
31 

32 
33 
34 

35 
36 
37 
38 
39 
40 



) Listing 19-1: exampleS.c 

#1 ncl ude "userapi . h" 
#include "balljfx.h" 

#define BALL_WIDTH 50 
#define BALLJEIGHT 50 

#define SCREEN JfiOTH 800 
#define SCREEN_HEIGHT 500 

#def1ne GRAVITY 3 
#define NUM.BALLS 1 

#define BASE_C0L0R Oxldab 

#define ROT^COLOR (a)(((a«1) + (a»14)) & 0x7fff) 

typedef struct { 
int X, y; 

int x_vel ,y_vel; 
} bai l_struct; 

void initiallze(void) 

void draw_screen(vol d); 

void draw_grid(void); 

voi d i ni t_bal I s(voi d) ; 

voi d ani m_bal I s(vo1 d) ; 

void cai c_pos(ba {Instruct * b); 

voi d draw_ba! I s(voi d); 

voi d erase_bal I s(voi d) ; 

voi d draw_tel emetry (voi d) ; 

void go_button(void); 

void stop_button(char * name); 

voi d reset_button(voi d) ; 

voi d ref resh_screen (voi d) ; 

bal Instruct baltsENUHIUALLS]; 
int step; 

void initial ize(void) { 
draw„screen(); 

step = 0; 
ini t_bal I s(); 

ti raer_start(100, "draw_tel emetry")} 

void draw_screen(void) { 

gf x„setgraphi cscontext (GFX JACKGROUNDBUFFER) ; 

gfx_cl earscr(RGB(0, 0, 0)); 

draw_grid(); 

gfx__setgraphi cscontext (GFX^SCREENBUFFER) ; 
gfx_copybuffer (GFXJACKGROUNDBUFFER. GFX^SCREENBUFFER) ; 

fiie is included in ttie SGOS installation CD-ROM tutorial file. 
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File Listing 19-1: exampleS.c (continued ) 

41 /* make the buttons */ 



42 fliakebuttonl ("GO! 10, 510, 100, 50, RGB(0, 255, 0) , "qo_button") ' 

43 niakefautton1("ST0P!M0,570,100,30,RGB(255,0,0), "stop button")- 

44 makebuttonl ("Reset", 120, 510, 50, 90, RGB(255, 255, 0) , "reiet button") ; 

45 setbuttonfont("GO!", "impact. ttf", 30); " 

46 } 

47 void draw_grid(void){ 

48 int x,y; 

49 int color; 

50 color = BASE^COLOR; 

51 for (y=0; y<=SCREEN JEI GHT-50; y+=:50) { 

52 for(x=0; x<=SCREEN_WI DTH-50; x+=50) { 

gfx Jrawbar(x, y, 50, 50, col or) ; 

54 color = ROT_COLOR(color); 

55 ) 

56 } 

57 } 

58 /** button callbacks *V 

59 void go_button(void){ 

60 ti ffler_start(100, "ani m^bal I s"); 

61 sound_pl ay ("button, wav") ; 

62 } 

63 void stop Jutton (char * name){ 

64 sys_debug("»» stop button: %s",name); 

65 ti mer_ki 1 1 ("anim^bal Is"); 

66 sound_pl ay ("button. wav") ; 

67 } 

68 void reset_button(void){ 

69 init_balls(); 

70 ref resh_screen () ; 

71 sound_pl ay("button. wav"); 

72 } 

73 /** telemetry display **/ 

74 void draw_telemetry(void){ 

75 char buf[60]; 

76 text_pri ntf (buf , "step %d" , step) ; 

77 gfx_setfont("georgi a. ttf ", 12) ; 

78 gfx_copybufferpart(500, 510, 300, 30, 

500, 510, GFX^BACKGRQUNDBUFFER, GFX_SCREENBUFFER) - 

79 gfx.drawstri ng(510, 530, buf, RGB(255, 255, 255), -1) - 



80 



tlmer_start(900, "draw_tel emetry"); 



81 } 

This me is included in the SGOS installation CD-ROM tutorial We, 
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File Listing 19-1: examples. c (continued) 



82 /** ball animation *V 

83 void init_balls(void) { 

84 I nt I ; 

85 for(i =0; I <NUM_BALLS; i ++){ 

86 balls[i].x = rnd_get_number(SCREEN_WIDTH - BALL^WIDTH); 

87 baHs[i].y = rnd_get^nuniber(SCREEN_HEIGHT - BALLJEIGHT); 

88 baHs[i].x_vel = rnd_get_number(200) - 100; 

89 balls[i].y_vel = rnd_get_number(200) - 100; 

90 } 

91 } 

92 void aniin_balls(vold) { 

93 int i; 

94 gf x^setgraphi cscontext (GFXJACKGROUNDBUFFER) ; 

95 erase_bal ls(); 

96 for (i =0; i <NUM_BALLS; i ++) { 

97 cal c_4)os(&bal I s[i ]); 

98 } 

99 draw^baJIsO; 

100 step++; 

101 gfx^setgraphi cscontext(GFX_SCREENBUFFER); //unneeded 
102 

gfx_copybuff erpart(0, 0, SCREEN_WI DTH, SCREEI\I_HEI GHT, 0, 0, 6FX_BACKGR0UI\IDB 
UFFER, GFX_SCREENBUFFER); 

103 ti mer_start(100, "ani m„bal I s"); 

104 } 

105 void draw_balls(void) { 

106 int i; 

107 for(i =0; i <NUMJALLS; 1 ++){ 

108 gfx_drawspri te(faal ls[i].x, bal ls[i].y, (char**)bal I); 

109 } 

110 } 

111 void erase_bal Is(void) { 

112 draw_grid(); 

113 } 

114 void refresh_screen(void) { 

1 1 5 gf x^setgraphl cscontext (GFX JACKGROUNDBUFFER) ; 

116 draw_grid(); 

117 draw„balls(); 

1 1 8 gf x^setgraphi cscontext (GFX^SCREENBUFFER) ; 
119 

gfx^copybuf ferpart (0, 0, SCREEN J/l DTH, SCREENJEI GHT, 0, 0, 6FXJACKGR0UNDB 
UFFER, GFX^SCREENBUFFER); 

120 } 



121 void cal c_4)os (bal Instruct * b) { 

122 b->x += b->x_vel ; 

123 b->y += b->y_vel ; 

124 b->y_ve! += GRAVITY; 
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File Listing 19-1: exampleS.c (continued) 

125 if(b->x <= 0){ 



126 b->x = 0; 

127 b<>x_vel = -(b->x^vel*8/10); 

128 }else if(b->x >= SCREEN_WIDTH - BALL3IDTH){ 

129 b->x = SCREEN_WIDTH - BALL.WIOTH; 

130 b->x_vel = -(b->x_ver8/10); 

131 } 

132 if(b->y <= 0){ 

133 b->y = 0; 

134 b->y__vel = -(b->y_vel *8/10); 

135 }else if(b->y >= SCREEOEIGHT - BALL^HEIGHT){ 

136 b->y = SCREEN^HEIGHT - BALLJEIGHT; 

137 b->y_vel = -(b->y_vel*8/10); 

138 } 



139 } 



This file is included in tiie SGOS instaliation CD-ROM tutorial file, 

4. When player presses Reset button: 

a. Re-creates all balls from scratch 

b. Plays a button sound 

The following review of the code in exampi eS. c focuses on changes from the previous exam- 
ple in Chapter 20: 

Ln 3-10 The definitions are unchanged from the last example, except that the screen height 
is reduced from 600 to 500, to allow room for the black bar at the bottom. 

Ln 29-34 The i nl ti ai i ze() routine still creates the initial ball positions and velocities. The 
previous example drew directly to the screen and used gfx_copybuffer() to set the 
frame buffer. Now you will use the frame buffer as an intemiediate step, as 
explained below in drawLscreen(). 

i ni ti al i ze() has a new step to start a timer for the telemetry string on the bottom 
of the display. 

Ln 35-46 The draiif_screen() routine uses the frame buffer this time as a true buffer, as fol- 
lows: 

gfx_setgraphicscontext(GFX_BACKGROUNDBUFFER) lets you draw directly into the 
frame buffer. Nothing will display on the screen. 

gfx_cl earscreenO clears the frame buffer. 

draw_gri dO is now a separate ftinction (see below), hi the last example it was part 
of InitiafizeC). 

After drawing the grid, gfx.setgraphicscontext(GFX_.SCREENBUFFER) sets the 
graphics context back to the screen, 

gfx_copybuffer() copies the frame buffer onto the screen buffer. 

inakebutton1("G0!",10,510,100,50,RGB(0,255,0),"go_button") creates a button 
named GO! . This button is located at (10, 510), and has a width of 100 and a height 
of 50. RGB(0, 255,0) defines its color as green. The callback ftinction go.button is 
called when the button is pressed. 
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The parameters for the Stop and Reset buttons are similar. 

setbuttonfontO changes the font and point size of the GO! button only. The other 
two buttons will use the button font default, which is Georgia 8 point. 

Ln 47-57 draw_jr 1 d() is a separate new function to draw the grid of colored boxes. The code 
is unchanged from the last example when it was a part of the i nitiai i ze() func- 
tion. 

Ln 59-62 The go_button() function is called when the GO! button is pressed. It simply starts 
a timer for the ball animation and plays a button sound. 



TIP... Your development system probably does not have sound capabilities. In the 
iocal.oti initialization file, sound must be an included option for [start:up]. 
Refer to the file listmg in Appendix D. 

Ln 63-67 The stop_button() function does the following: 

Prints a debug statement giving the parameter passed. If a callback function passes 
a parameter, the parameter is the name of the button pressed. You could have set up 
several buttons that call the stop.button() function, but this example has only the 
one button named Stop. So the parameter is always Stop. 

Deletes all the timers having anin.ballsO as a callback function. This action 
freezes the animation. 

Plays a button sound. 

Ln 68-72 The reset_button() function re-runs i nl t_bal I s() and ref resh_screen(). Then it 

plays the button sound. 

Ln 74-81 The draw_tel eraetry () function does the following: 

Allocates a character buffer and writes into it using text_printf(), which works 
just like the standard library function pri ntf (). 

Sets the current font to 12 point georgi a. ttf, erases whatever is now in the display 
spot and draws the string on the screen. 

Starts a timer to make a callback to itself Notice that this is the second timer loop 
that is drawing to the screen. (The other one is for animation of the balls.) This 
does not create any problems since they draw to different areas of the screen and 
don't interfere with each other. 



TIP... No standard C calls are permitted in game code, to preserve the integrity of 
the pre-approved library and game engine. This includes file I/O and the pri ntf 
family. For instance, this example uses text_pri ntf () from the SGOS library 
instead of spri ntf () . 



Ln 83-91 i ni t_bal I s() is now a separate function to set up each balPs location and velocity. 

The code is unchanged from the last example when it was a part of the i ni ti ai - 
' i ze() function. 

Ln 92-104 The function an! ia_bal I s() is refined from the way it worked in the previous exam- 
ple. The animation logic is still the same, but now you draw to the frame buffer 
first and then draw to the screen. The steps in ani Oal I s are as follows: 

Set the graphics context to GFX.BACKGROUNDBUFFER. 
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Erase all present balls from the frame buffer by redrawing the entire colored grid. 
Update the positions of all the balls with draw^bal I s(). 
Draw all the balls into the frame buffer. 

Set the graphics context back to GFX.SCREENBUFFER to draw to the screen. 

Copy the entire checkered area with flie balls from the frame buffer to the screen. 
This single screen update greatly reduces flicker. 



As its last step, ani n_bal I s starts a timer with a callback to itself 

Ln 105-10 draw.bal I s() has become a separate function in the current example. It switches to 
gfx_drawsprite() to handle transparency. 



Recall from the last example that the gfx_drawtransXPII() transparency mechanism 

erased overlapping parts of ball images as new ones were added. Since 
gfx_drawsprite() replaces transparent pixels with the pixels from the current 
buffer (in this case the frame buffer), each new ball placement will put only the ball 
itself into the current frame buffer. All the transparency of the ball's rectangular 
border will be replaced with appropriate pixels from the current frame buffer. 



Ln 111-13 erase^al ls() simply redraws the entire colored grid. This complete redraw is a 



somewhat primitive approach, but it works well for this example. Chapter 
Double-Buffered Animation, gives an example of a more advanced graphics updat- 
ing approach. 



Sets the graphics context to the GFX„BACKGROUNDBUFFER. This approach will copy all 

changes to the screen at once, giving a nicer presentation. 

Erases all the balls by having draw^grl d() redraw the screen. 
Creates new ball positions and velocities with i ni t_bal I s(). 
Draws the balls on the screen. 

Sets the graphics context back to the GFX_$CREENBUFFER so all the new balls can be 
drawn to the screen at once. Then it copies the rectangle, defined from the upper 
left comer of the screen and SCREEOI DTH x SCREEN^HEi GHT in size, to die screen. 



Ln 1 21 -39 cal c jJOs() is unchanged from before. 

D. Make, Compile, and Run the Program 

Make and compile the program the same as in the last example. Change the example file name 



Ln 114-20 



The ref resh„screen() frinction has the following steps: 
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to exampi eS. c. Also, include the sound file button, wav. 




Figure 19-*1 - Tutorial: Screen with Buttons 



When you run the program you will see a checkered display with a black bar along the bottom, 
as shown in Figure 19'L There are three buttons: GO! , Stop, and Reset. Click on the GO! button 
to start the animation. Press Reset to give the balls a random new position and velocity 

If you press 60! more than once, it will keep spawning animation timers, and the balls will 
move faster up to a point. The animation loop moves all balls each time it is called. It does not 
care which timer loop called it, so more timers will just speed things up. 

If you then press Stop, all the animation timers will be deleted and the balls will stop. 

E. Circumstance Where Callbacks Are Not Stopped by timer_kill() 
1 . Why the Animation May Not Stop 

If a lot of timers are running when you press Stop, the animation may fail to fully stop. 
When many timers are running, it is likely that one or more of them will still be waiting in 
the event queue. Once a timer times out, only the callback function remains; it is no longer 
a "timer" and is no longer affected by the t i mer^ki 1 1 () function. 

The more animation timers there are, the greater the chances the ti nier_ki 1 1 () ftinctions 
will not stop a timer callback. If there are as many as 30 animation timers, this phenome- 
non of callbacks slipping through the queue may happen to more than one timer. SGOS 
does limit the number of timers that can be running at one time (maximum is 60), 

The debug, out file lists timers by the time remaining on them, in the order of increasing 
time left. Timers are not associated to numbers, so you cannot track a particular timer 
through the debug, out file, debug, out is more useful to see how many timers are executing 
at one time. 
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2. A Sure Way to Stop the Animation 



There IS anoAer way you can set up the on-off switches. Use a global variable as a bool- 
ean tellmg whether the animation is running. Check this global variable in go_button() If 
flie anunation IS not running, set the flag and start the animation. In this chapter's example 

SZli K -^^ T '° ^^"^^^^ ' 0 checks each time to see tf 

should be anmiating by looking at the flag. If not, the timer is not renewed. 

F. Exercises 

The following exercises sho>* some fiuther nuances of how buttons and timers work in SGOS: 

^' ^LTLuT'I!!"''-'^ '^^^ ^'"^^t^^r ™tion is with 

more balls than the previous example. 

2. The example program as written allows many animation timers by repeatedly pressing 

SLI'^ST"^ L^^T ^*°P' p'-^g^^ look i 

debug, out for »», the characters at the front of the stop button string. Just above the 
>>>> you will see a listmg of most of the 30 timers. After the »» there should be a 
short hstmg of timers that did not stop before you quit the program. One of these timers 
^ the telemetry timer which you did not kill. All the others are for the animation loop 
How many slipped through the ki 1 1 _ti mer () call on the event queue? 
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Chapter 20 — Using Timers to Move an Icon 



A. Overview 

The icon in the previous example flashed and blinked but stayed in one position. This chapter 
makes the ball icon move. The tutorial will include the following SGOS tools and concepts: 

• Using a structure to give the ball position and velocity 

• Getting a random number from the SGOS library 

• Using the SGOS debug statement 

• Using the SGOS "sprite" graphics function to avoid clipping in animations 

B. Getting a Random Number From the SGOS Library 

This chapter will use random numbers to move balls around the screen at varying velocity. 
SGOS includes its own random number generator. Use the API function 

rnd_get_number(range) 

to return a random number between zero and range. Refer to Appendix C for more about this 
function. 

C. Debug Settings 

The API call sys_debug(char* foroat, . . . ) prints the named forinats to the file debug, out. 
This chapter will use it to find the ball's current position. Refer to Chapter I4-E, Debugging 
Tools for more about SGOS debugging options. 

D. Writing a Program That Moves an Icon 

Copy exampi e4. c, as listed in File Listing 20-1, to your app. tutori al directory. This example 
will move a ball around the screen and demonstrate a few important points about transparency. 
It will again use the ball icon from Chapter 1 7, and will add code to provide and display ball 
position and velocity. Following is a review of the code in exampi e3. c: 

Ln 1-2 Include userapi . h and bal l^fx. h as in the previous examples. 
Ln 3-1 0 Define several constants: 



BALL.WI DTH and BALL„HEI 6HT are the width and height of the ball graphic in pixels. 
SCREENJI DTH, SCREEN JEI GHT are set, also in pixels. 

GRAVITY is the acceleration of the balls to the bottom of the screen, in no particular 
units. 

NUII_6ALLS is the number of balls handled in the program. 

Lines 9 and 10 define the BASE.COLOR and ROT_COLOR, which steps through several 
colors by incrementing the color character value. 



Ln 11-14 Declare a ball structure. The structure contains the ball's position on the screen and 
its velocity. 

Ln 15-20 Create global variables to keep information between timer callbacks: 
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File Listing 20-1: exampie4.c 

1 #include "userapi.h" 

2 #include "ball ^fx.h" 

3 #define BALL_WIDTH 50 

4 #define BALLJEIGHT 50 

5 #define SCREENJIIDTH 800 

6 #define SCREEN.HEIGHT 600 

7 #define GRAVITY 3 

8 #def i ne NUM.BALLS 1 

9 #def i ne BASE_C0L0R 0x1 dab 

10 #define ROT^COLOR (a)(((a«1) + (a»14)) & 0x7fff) 



11 typedef struct { 

12 Int x,y; 

13 int x_vel ,y_vel ; 

14 } bal I ..struct; 

15 void initialize(void); 

16 void draw_screen(void); 

17 void aniin_balls(void); 

18 void calc_pos(baH_struct * b); 

19 bal I .struct bal I sCNUMJALLS] ; 

20 int step; 

21 void lnitiali2e(void) { 

22 int i; 



23 draw„screen(); 

24 gf x.copybuf fer (GFX^CREENBUFFER, GFX JACK6R0UNDBUFFER) ; 

25 step = 0; 

26 for(i =0; i <NUI« JALLS; i ++) { 

27 balls[i].x = rnd.get.number(SCREEN.WIDTH - BALL_WIDTH); 

28 balls[i].y = rnd_get_number (SCREEN JE I GHT - BALL_HEIGHT); 

29 bal ls[i],x_vel = rnd_get.number(200) - 100; 

30 balls[i],y_yel = rnd_get_nuinber(200) - 100; 

31 } 

32 ti nter_start(100, "ani m^bal I s") ; 

33 } 

34 void draw_screen(void) { 

35 Int x,y; 

36 int color; 

37 gfx_cl earscr(RGB(0, 0, 0)); 

38 color = BASE_COL0R; 

39 for(y=0; y<=SCREEN JEI GHT-50; y+=50) { 

40 for (x=:0; x<=SCREEN_WI DTH-50; x+=50) { 

41 gf x_drawbar (x, y , 50, 50, col or) ; 



This file is included in the SGOS installation CD-ROM tutorial file. 
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File Listing 20-1: example4x (continued) 



42 




color = ROT COLOR(color); 


43 




} 


A A 

44 




} 


45 


} 




46 


void aniin_bal Is(void) { 


47 




int i ; 


48 




for(i =0; i <NUMJALLS; i ++){ 


49 




gfx_copybufferpart(ba! I s[i ] . x, bal 1 s[i ] , y. 


91) 




BALLJIf 1 DTH, BALLHEI GHT, 


C1 
OJ 








bal 1 s£i ] . X, bal 1 s[i ] . y, GFX JACKGROUNDBUFFER, GFX_SCREENBUFFER) ; 






calc_pos(&bal ls[i]); 


53 




sys_debug("»> step=%d\tbal 1 =%d\tv''2=%d", step, i , 


54 




bat 1 s[i ] . x_vel *bal 1 s[i ] . x„vel 






+bal ls[i],y_vel *balls[i].y_vel); 


5b 




} 


5/ 




for(l =0; i <NUM_BALLS; i ++) 


58 




gfx_drawtransXPM(bai 1 s[i ] . x. ball s[i ] . y. 


59 




(char**)baH,"99"); 


cn 
OU 




step++; 


61 




ti iner_start(100, "ani ni_bal 1 s"); 


62 


} 




63 


void calc_pos(ball_struct * b) { 


C A 

64 




b->x += b->x_vel ; 


tic 

65 




b->y += b->y_vel ; 


DO 




b->y_vel += GRAVITY; 


0/ 




if(b->x <= 0){ 


Do 




b->x = 0; 


by 




b->x_ve! = -(b->x_vel *8/10); 


/u 




}else if(b->x >= SCREEN.WIDTH - BALL_WIDTH){ 


71 




b->x = SCREEN_WIDTH - BALL^WIDTH; 


72 




b->x vel = -(b->x vel*8/10); 


73 




} 


74 




if(b->y <= 0){ 


75 




b->y = 0; 


76 




b->y_vel = -(b~>y vel*8/10); 


77 




}else if(b->y >= SCREEN_HEIGHT - BALLJE1GHT){ 


78 




b->y = SCREEN„HEIGHT - BALL„HEI6HT; 


79 




b«->y vel = -(b~>y vel*8/10); 


80 




} 



This file is included in the SGOS installation CD-ROM tutorial file. 



bal I s is the array holding all of the ball structures, 
step is a counter of times through the animation loop, 

Ln 21-33 The function i ni tl al i ze() will be called by SGOS on startup. 

Call draw_screen() to draw the checkered pattern, then use gfx_copybuffer() to 
copy the entire screen buffer into the frame buffer for use to refresh the display 
when the ball(s) moves. 
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Initialize the global variable step and each of the bal I s£i ] in the balls array. This 
routine uses random numbers to initialize the ball array. The code uses 
rnd_get_nuniber(200) - 100 to generate velocities in the range -100<=x<100- 

Now that everything is set up, start a timer to begin the animation. 

Ln 34-45 draw_screen() does the following: 

Clears the screen buffer to black using gfx_cl earscr(RGB(0, 0, 0), 

Draws the boxes, using a for loop to rotate through colors using the variable c. 

Ln 46-62 ani in_bal I s() does the following: 

For each ball in the array: Uses gfx_copybuff erpart to erase it from the screen by 
copying the relevant part from the specified source, the frame buffer (the back- 
ground), to the destination buffer, the screen buffer; then calculates the ball's new 
position and print a debug statement. 

A'fter all balls are erased and updated, gfx_drawtransXPM() enlists the for loop to 
draw each ball to the screen. 

To keep things going, start a timer to call ani m_ba M s () back in . 1 second. 

Ln 63-80 calc_pos() contains nothing related to SGOS. It calculates a ball's new position 
and velocity, including factors for inelastic collisions with the sides of the screen 
and gravity. 

E. Running THE Program 

Run the program the same as in the previous examples. After the startup screen you should 
again see the screen filled with a checkered pattern. A single ball icon will move around the 
screen, because you inially set NUII3ALLS to 1. Figure 20-1 shows how the screen should look, 
exampl e3. c will slowly run down because the balls have "gravity," Press q to quit. 




Figure 20-1 - Tutorial: Timers and a Moving Icon 



F. Using Sprite to Fix Animation Clipping 

If you have not tried it already, increase NUM^BALLS and run the program again. 
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Notice that the ball icons' rectangles clip each other and hide portions of the balls that should 
be displayed. This happens because gfx_drawtransXPM() replaces the transparent pbcels in a 
graphic with the appropriate pixels from the frame buffer. In effect, the gfx_drawtransXPH() 
transparency mechanism erases overlapping parts of any ball images already drawn to the 
screen. 

Using a sprite animation function will resolve the clipping because it handles transparency 
differently. The function gfx_drawspri te() will replace the transparent pixels with the appro- 
priate pixels -from the current buffer, which in this case is the screen. 

The next tutorial example will use spri te functions. 

G. Exercises 

Try the following: 

1 . Experiment with gfx^drawspri te() if you want to see its effect. Refer to Appendix C. 

2. When you increase the number of balls you will see them flicker as they collect near 
the bottom of the screen. The next examples will show refined ways to update screens 



to minimize flicker. 
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Chapter 21 — Tutorial: Using Nvram 



A. Overview 

This chapter shows how to use the non- volatile RAM (nvram) to preserve data among multiple 
program modules. The tutorial will include the following SGOS tools and concepts: 

• How SGOS lets you interact with nvram 

• Using the nvram file in place of nvram hardware on your development computer 

• An improved graphics technique 

• More buttons to show more interactions among multiple game functions 

B. Adding nvram to Preserve Data 

To satisfy security and accounting requirements, all computer-based games of chance must be 
able to preserve data across executions. This chapter introduces SGOS nvram storage with an 
example that remembers two structures to store ball positions^ Chapter 9 explains more about 
how SGOS uses the game, state file to handle nvram data. Appendix C describes the API 
nvram routines. 

Since your desktop computer will not have nvram hardware, you must use a file called nvram 
in its place. The file I oca I . oti disables nvram hardware for development (it also disables the 

touch screen and other game hardware). Refer to Appendix D and Chapter 2-2, Installing and 
Configuring SGOS, While you are developing a game, SGOS will use your nvram file as a 
proxy for the nvram hardware. 

C. Use of Multiple Game Modules 

Spreading code among different modules can help keep it cleaner. Whenever you load a new 
module, SGOS first unloads everything from memory in the current module and calls 
nod_exi t(), then it loads the new module into memory and calls initial ize(). nvram is the 
only way you can pass parameters between modules. 

Yor must name your game's main module game, so for it to work correctly. Other modules can 
have any name. This chapter creates a separate module for the ball's "gravity" function. The 
file called gravi ty . c becomes gravi ty. so when compiled. 

D. Graphics Handling Alternatives 

The example in the preceding chapter used a primitive animation scheme that redrew the 
entire background image with all the balls each time through the loop. It then copied the entire 
background image to the screen each time. 

You really only need to redraw enough of the background to erase each ball and copy all 
changes from the background to the screen. However, this example with the multiple balls will 
stay with the primitive approach. The rectangle tracking scheme for multiple updates would 
get unwieldy. 
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Chapter 7-M, Double-Buffered Animation explains how to use a more sophisticated approach 
for localized screen updates. 

Though still elementary, the draw_tel eoetry () function does use a more localized approach 
for its screen update, which would reduce flicker. It first updates the frame buffer with the 
original background — solid black — and then draws its new string in the frame buffer. 
Finally, it copies the rectangle with the changed part of the frame buffer to the screen. In this 
case the string never moves, the backgroimd is very simple, and there are no other overlapping 
images. 

E- Create A GAME-STATE File 

SGOS uses the gane. state file to store variables and structures during and between games. 
You will store two structures in game, state in this example. File Listing 21'] shows the code 

File Listing 21-1: game.state file for example6,c 

1 struct bal I Jnfo{ 

2 char initial i zed; 

3 \ nt num^bal I s; 

4 int step; 

5 int moving; 

6 i nt gravi ty__x CALLBACK(upcIate_gravi ty) ; 

7 int gravi ty_y CALI-BACK(update_gravi ty) ; 

8 } Info; 



15 } Ban [50]; 

This file is included in the SGOS installation CD-ROM tutorial file. 

to store struct bal l_i nfo and struct bal I . These two structures store all the ball data that 
will be needed between modules, so the game can continue as the modules are loaded and 
unloaded. 

F. Create Module for example6.c 

As a game gets more complex it is helpful to break it up into several working modules. For the 
current example you will create two program files that will act as two distinct modules: 

• exainpl e6. c will start, stop, and run most of the ball actions 

• gravi ty. c will provide buttons to adjust a directional "gravity" property 

The following is a review of the code in exanpl e6. c (refer to File Listing 21-2). 

Ln 1-3 These included files should look familiar from the other examples. For exaropi e6. c 
you are also adding a second ball, bal I _red_gfx. h. ***blue?*** 

Ln 4-11 Most of the defined ball properties also look familiar, but there are two changes. 

Now you define IIAX_BALLS instead of NUM.BALLS because the new program has but- 



9 

10 
11 

12 
13 
14 



Struct bal I { 
int x; 
i nt y; 



I nt x_vel ; 
i nt y_vel ; 



int handler; 
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File Listing 21-2: example6,c (sheet 1 of 7) 

1 #inciude "userapi.h" 

2 #include "ball_gfx.h" 

3 #include "bat l^red^gfx. h" 

4 #define BALLJIDTH 50 

5 #define BALLJEIGHT 50 

6 #define SCREEN^WIDTH 800 

7 #define SCREEN.HEIGHT 500 

8 #derine MAX.BALLS 50 

9 #define NUM.HANDLERS 2 

10 #define BASE^COLOROxIdab 

11 #define R0T_C0L0R(a)(((a«1) + (a»14)) & 0x7fff) 

12 /♦* the bail structure *V 

13 typedef struct { 

14 int x,y; 

15 int x_vel , y_vel ; 

16 int handler; 

17 } ball ..struct; 

18 /** prototypes **/ 

19 void initiaMze(void); 

20 void draw_screen(void); 

21 void draw_grid(void); 

22 void go_button(void); 

23 void stop_button(char * name); 

24 void reset_button(void); 

25 void remeinber_fautton(void); 

26 void recal l_button(void); 

27 void more_button{void); 

28 void less_button(void); 

29 void gravity_button(void); 

30 void draw_telemetry(void); 

31 vol d i ni t_bal I (i nt number) ; 

32 void ini t_bal Is(void); 

33 void anim_bans(void); 

34 void draw_balls(void); 

35 void refresh_screen(void); 

36 void add_rectangl e(i nt x, int y, int w, int h); 

37 void copy_rects(void); 

38 void redraw_framebuffer(void); 

39 void calc_pos(ball_struct * b); 

40 void calc_4)0S_rnd(bal Instruct * b); 

This file is included in the SGOS installation CD-ROM tutorial file. 
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41 

42 
43 
44 
45 
46 
47 

48 

49 
50 

51 
52 
53 

54 
55 

56 
57 
58 
59 

60 
61 
62 
63 
64 
65 

66 
67 
68 

69 
70 
71 

72 

73 

74 

75 

76 



Listing 21-2: exampleG.c (sheet 2 of 7) 

/** global s *V 

bal I ^struct bal I s[MAX_BALLS] ; 

int step; 

i nt nuni_bal I s; 

int is_inoving; 

int gravity_x; 

int gravity_y; 

/** main function **/ 

void Initial I ze(void) { 
draw_screen(); 

step = 0; 
num_bal I s = 1; 
is_inoving = 0; 

nv_geti nt(" I nfo. gravi ty_x", &gravi ty_x) ; 
nv_geti nt (" I nfo. gravi ty_y" , &gravi ty_y) ; 

Ini t_bal I s(); 
ref resh_screen() ; 

ti mer_start(100, "draw_tel emetry"); 



void draw_screen(void) { 

gfx„setgraphi cscontext (GFXJACKGROUNDBUFFER) ; 

gfx„cl earscr(RGB(0, 0, 0)); 

draw_grid(); 

gfx_setgraphi cscontext(GFX_SCREENBUFFER) ; 
gfx_copybackground() ; 

/* make the buttons */ 

makebuttoni ("GO! '\ 10, 510, 100, 50, RGB(0, 255, 0), "go_button"); 
setbuttonfontC'GOl", "impact. ttf", 30); 

makebuttoni ("STOP! 10, 570, 100, 30, RGB(255, 0, 0), "stop_button"); 
makebuttoni ("Reset", 120, 510, 50, 90, RGB(255, 255, 0) , "reset„button"); 
makebuttoni ("Remember", 180, 510, 100, 40, RGB(100, 0, 255), 

" remeraber„button") ; 
makebuttoni ("Recal I 180, 560, 100, 40, RGB(255, 0, 255) , 

"recal l_button"); 
makebuttoni ("More Bal I s", 290, 510, 100, 40, RGB(255, 200, 200) , 

"more_button"); 
makebuttoni ("Less Bal I s", 290, 560, 100, 40, RGB(200, 200, 255), 

"less^button"); 
makebuttoni ("Gravi ty", 400, 510, 100, 40, RGB(200, 255, 200), 

"gravi ty^button"); 



file Is included in the SGOS installation CD-ROM tutorial file. 
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File Listing 21-2: example6,c (sheet 3 of 7) 
77 void draw_grid(void){ 



78 int x,y; 

79 int color; 

80 color = BASE_COLOR; 

81 for(y=0;y<=SCREEOEI GHT-50; y+=50) { 

82 for(x=0; x<=SCREEN_WI DTH-50; x+=50) { 

83 gfx_drawbar (x, y, 50, 50, col or) ; 

84 color = R0T„C0L0R(color); 

85 } 

86 } 

87 } 

88 /** button callbacks **/ 

89 void go_button(void){ 

90 sound_pl ayC'button. wav") ; 

91 if(!is_inoving) 

92 ti mer_start{100, "ani in_bal I s"); 

93 isjoving = 1; 

94 } 

95 void stop_button(char * naine){ 

96 sys_debug("»» stop button: %s",naine); 

97 ti mer_ki 1 1 ("ani ni„bal 1 s"); 

98 is_nioving = 0; 

99 sound_pl ay ("button, wav") ; 

100 } 

101 void reset_button(void){ 

102 tnit_balls{); 

1 03 ref resh_screen () ; 

104 sound_pl ay("button. wav") ; 

105 } 

106 void reineinber„button(void){ 

107 int i; 

108 nv„setchar("I nfo, i ni ti al i zed'M); 

109 nv_seti nt (" 1 nfo. nuni_bal I s", num_bal i s) ; 

110 nv.seti nt(" I nfo. step", step) ; 

111 nv^seti nt("l nfo. movi ng", i s_movi ng); 

112 for(i =0; i <nura_bal I s; i ++){ 

113 nv_seti nt("Bal 1 [%d] . x", ball s[i ] . x J ); 

114 nv„seti nt("Bal I [%d]. y", bai I s[i ] . yj ); 

115 nv_set1 nt("Bal I [%d]. xjvel bal I s[i ] . x„vel , i ); 

116 nv_seti nt("Bal I [%d] . y_vel *\ bal I s[i ] . y^vel J ) ; 

117 nv_setint("Bal I [%d], handl er", bai I s[i ]. handl er, i ); 

118 } 



This file is included in the SGOS installation CD-ROM tutorial file. 
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119 sound^pl ayC'button. wav"); 

120 } 

121 void recal l_button(void){ 

122 char init; 

123 intj; 

124 int was_moving; 

125 nv_getchar("lnfo. initial i zed", &i nit); 

126 if(init){ 

127 was_moving = is_moving; /*remember moving state for later*/ 

128 nv_geti nt("l nfo. nuni^bal I s", &nuni_bal I s); 

129 nv^geti nt("l nfo. step", &step); 

130 nv_geti nt("l nfo. movi ng", &i s^movi ng) ; 

131 for(i =0; i <num_bal I s; i ++){ 

132 nv jeti nt("Ba! I [%d].x",&balls[l].xj); 

133 nv_geti nt("Bal I [%d] . y", &bal I s[i ] .y, i ); 

1 34 nvjjeti nt ("Bal I [%d] . x^vel ", &bal I s[i ] . x_vel , i ) ; 

135 nv_aeti nt("Bal I [%d] , y_ve! ", &bal I s[i ] . y^vel , i ) ; 

1 36 nv^eti ntC'Bal I [%d] , handl er", &bal J s[i ] . handl er, i ); 

137 } 

1 38 ref resh_screen () ; 

139 i f (i s_movi ng && ! was^movi ng) 

140 /* this will start a timer only if one is not already V 

141 /* going, if one is already going and it needs to be */ 

142 /* turned off, it will turn itself off after looking at */ 

143 /* is_nioving */ 

144 ti mer_start(100, "ani m_bal I s") ; 

145 } 

1 46 sound_pl ay ("button, wav") ; 

147 } 

148 void more„button(void){ 

149 i f (num_faal I s < MAXJALLSX 

150 num_balls++; 

151 i ni t_bal I (num_bal I s) ; 

152 i f (li s_movi ng) 

1 53 ref resh^screen () ; 

154 > 

1 55 sound_pl ay ("button, wav") ; 

156 } 

157 void less_button(void){ 

158 ff(num_balls>1){ 

159 num_balls--; 

160 if(! is_moving) 

1 61 ref resh_screen 0 ; 

162 } 

This file is included in the SGOS installation CD-ROM tutorial file. 
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File Listing 21-2: exampleS.c (sheet 5 of 7) 

163 sound_pl ay("button. wav") ; 

164 } 

165 void gravi ty_button(void){ 

166 mod J oad ("gravi ty"); 

167 } 

168 /** telemetry display **/ 

169 void draw_teleffletry(void){ 

170 char buf[60]; 

171 text_pri ntf (buf, "step %d, num, bal I s %d", step, num_bal I s); 

172 gfx_setfont("georgl a. ttf 12); 

173 gfx_setgraphi cscontext(GFXJACKGROUNDBUFFER) ; 

174 gfx^drawbar (500, 510, 300, 30, RGB (0, 0, 0) ) ; 

175 gfx_drawstri ng(510, 530, buf, RGB(255, 255, 255), -1); 

1 76 gf x_setgraphi cscontext (GFX^SCREENBUFFER) ; 
177 

gfx_copybufferpart(500, 510, 300, 30, 500, 510, GFX JACKGROUNDBUFFER, GFX SC 
REENBUFFER); 

178 ti mer_start(900, "draw_tel emetry"); 

179 } 

180 /** ball animation **/ 

181 voi d i ni t_bal I (i nt number) { 

182 balls [number ].x = rnd„get_number(SCREEN_WI DTH - BALL_WIDTH); 

183 bal ls£nufflber].y = md_getjumber(SCREEN_HE! GHT - BALLJEIGHT); 

184 ball s [number]. x_vel = rnd_get_number(100) - 50; 

185 balls [number]. y^vel = rnd_get_number(100) - 50; 

186 ^ bal Is [number]. handler = rnd_get_nufflb^r(NUM„HANDLERS); 

188 void init_.bal Is(void) { 

189 int i; 

190 for(i =0; i <num„bal I s; i ++){ 

191 init_ball(i); 

192 } 

193 } 

194 /** animation loop *V 

195 void anim^bal Is(void) { 

196 int i; 

197 if(!is_moving) 

198 return; 

199 for (i =0; i <num_bal I s; i ++) { 

200 swi tch(baMs[i ], hand! er){ 

201 case 1: 

202 cal cjos.md(&bal I s[i ]); 
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File Listing 21-2: exampleS.c (sheet 6 of 7) 



203 break; 

204 defaul t: 

205 cal c^pos (&baJ I s [i ] ) ; 

206 } 



207 } 

208 step++; 

209 ref resh_screen () ; 

210 ti mer_start(100, "ani m^bal I s"); 

211 } 

212 /** screen handling functions **/ 

213 void draw_ba lis (void) { 

214 int i; 

215 char ** icon; 

216 for(i =0; i <num_bal I s; i ++){ 

217 if{balls[i]. handler == 1) 

218 icon = (char**)bal l_red; 

219 else 

220 icon = (char**)baH; ***NOTE-FIXING — balls get stuck 

221 gfx_drawsprlte(bal ls[i].x, balls[i].y, icon); 

222 } 

223 } 

224 void refresh_screen(void) { 

225 gf x^setgraphi cscontext (GFX JACKGROUNDBUFFER) ; 

226 draw_grid(); 

227 draw_balls(); 

228 gf x_setgraphi cscontext (GFX^SCREENBUFFER) ; 
229 

gfx_copybufferpart(0, 0, SCREEN.WI DTH, SCREEN_HEI GHT, 0, 0, GFX.BACKGROUNDB 
UFFER, GFX^SCREENBUFFER) ; 

230 } 

231 /** ball movement routines **/ 

232 void calc_pos(baM_struct * b) { 

233 b->x += b->x_vel; 

234 b->y += b->y_vel ; 

235 b->x_vel += gravity^x; 

236 b->y_vel +=: gravity_y; 

237 if(b->x < 5){ 

238 b->x = 5; 

239 b->x_vel = -(b->x„vel *8/10); 

240 }else if(b->x > SCREEN_WIDTH - BALL_WIDTH - 5 ){ 

241 b->x - SCREEOIDTH - BALLJWIDTH - 5; 

242 b->x_^vel = -(b->x_vel *8/10); 

243 } 

244 if(b->y < 5){ 

245 b->y = 5; 

246 b->y_vel = -(b->y_vel *8/10); 
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File Listing 21-2: exampleG.c (sheet 7 of 7) 



247 }else if(b->y > SCREENJEIGHT - BALL.HEIGHT - 5){ 

248 b->y = SCREEN_HEI GHT - BALLJEIGHT - 5; 

249 b->y_ve! = -(b->y_vel *8/10); 

250 > 

251 } 

252 void calc_pos_rnd(bal l_struct * b) { 

253 b->x += b->x_vel ; 

254 b->y b->y_ve!; 

255 b->x_vel += rnd_get_nuniber(3) - 1; 

256 b->y„vel += rnd_get_nuinber(3) - 1; 

257 if(b->x < 5){ 

258 b->x = 5; 

259 b->x^vel = -(b->x„vel *8/10); 

260 }else if(b->x > SCREEN JIDTH - BALLWiDTH - 5 ){ 

261 b->x = SCREEN_W1DTH - BALL_WIDTH - 5; 

262 b->x_vel = -(b->x_vel *8/10); 

263 } 

264 if(b->y < 5){ 

265 b->y = 5; 

266 b->y^vel = -{b->y^vel *8/10); 

267 }else if(b->y > SCREEN JEI GHT - BALLJEIGHT - 5){ 

268 b->y = SCREEN_HEIGHT - BALL JEI GHT - 5; 

269 b-.>yjvel = -(b->y_vel *8/10); 

270 } 

271 } 



This file is included in the SGOS installation CD-ROM tutorial file. 
tons to increase and decrease the number of balls. 

You also have a new property called NUH.HANDLERS with a default value of 2. "Han- 
dlers" refers to the functions that update a balPs position on the screen. This integer 
value is used in line 186 in rnd__get^number(NUII_HANDLERS). The program ran- 
domly chooses one of the handliers and applies it in several routines using 
bal 1 s [number] . hand! er. 

The list of prototypes has grown to cover new buttons and routines. 

The global variables include the array bal I_struct bal is[MAX_BALLS] to hold all 
of the ball information, plus step to count the animation steps, num.bal I s to track 
the total number of balls on the screen, and the flag i s.movi ng to tell whether ani- 
mation is active. 

The I ni ti al i ze() function is mostly familiar. There are now more global variables 
to initialize. The call to init_balls() initializes the ball array. Then the call to 
refresh_screen() draws the balls to the screen, and the last line starts a timer for 
the telemetry display. 

draw_screen() sets the graphics context to the frame buffer, draws the main screen, 
and copies the frame buffer to the main screen. You then make all seven buttons. 

The drawjridO, go_button(), and stop.buttonO functions are straightforward. 
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Ln 60-76 
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21-10 



Note that go.button checks the animation flag and stop^button resets it to 0. 
Lri 101-05 reset_button() is simpler since all the drawing of the balls now resides in the sub- 



routine refresh_screen(). Now it simply resets all the balls, then redraws the 
screen. 



The nv_setchar() and nv__setint() API functions save all the relevant ball infor- 
mation to nvram. Note that if you use a wrong character type, file debug, warn will 
print a warning. 

Using nv_seti nt (" I nfo. nun.bal I s", num.bai Is) as an example, the first argument 
is the name of the variable you are writing to, as a string. The second argument is 
the value you are saving. 

Additional values are substituted into the initial string according to pri ntf () style 
formatting. Any pri ntf () formatting characters are allowed, since SGOS makes 
the substitution using a call to vsprintf(). This parameter substitution does not 
care about syntactic meanings; the string is only interpreted after the substitution. 
Strings such as Bal i [%d] .%s[%d] or even %s[%d] are allowed, as long as they 
expand into a meaningful string. 



Ln 121-47 recal l_button() now fetches what reniember_button() stored in nvram. First you 



confirm that the nvram contains a valid saved position with Info. Initial ized. If 
there is a valid state, you use the nv_geti nt() API function to retrieve the number 
of balls, the step, and whether the balls were moving. 

You then load in all the ball data. If the balls were moving you start a timer to ani- 
mate the balls, if an animate timer is not already running. 



Ln 148-56 inore_button() adds another ball by incrementing nura_balls, if the total is still 



within IIAX_BALLS. The new ball is initialized the same as the other balls. If the balls 
are not currently animated, you redraw the screen. Otherwise the screen will be 

redrawn in the next animation loop. 



Ln 157-62 I ess_button() removes a ball by decreasing num.bal Is, to a value as low as 1. 
Again, if the balls are not moving you redraw the screen. 

Ln 165-67 gravi ty_button() loads the library gravity. After compiling, the full name of the 



file loaded is gravity. so. You pass the name with the extension .so. As noted at 
the beginning of this chapter, SGOS changes modules by unloading everything in 
the current module, calling mod.exi t(), loading the new module into memory, and 
calling ini tial ize(). 



Ln 169-79 draw_tel enietryO makes a local screen update as discussed in Graphics Handling 



Alternatives at the beginning of this chapter. The routine formats the telemetry 
string and loads the font you specify, switches to the frame buffer, redraws the 
background (solid black in this case) with a call to gfx_drawbar(), draws the 
telemetry string with gfx_drawstring(), and then copies the boxed area to the 
screen. 



Ln 181-87 init_bal!0 initializes a new ball record. This new function is called by 



more^button, to initialize each added ball. It also randomly assigns a handler to 
each ball with ball s[nuniber]. handler = rnd_get_nuinber(NUM_HANDLERS)« 



Ln 188-93 1 ni t_bal I s() re-initializes all the active balls. 

L 1 95-211 ani m_bal I s() updates all the ball positions if the flag i s^movi ng confirms the pro- 



Ln 106-20 



remember^buttonO is a new routine: 
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gram is currently animating. Note that each ball is "handled" according to its 
assigned handler, so balls can have different behaviors. 

anin.bal ls() then redraws the entire screen (in the frame buffer) with a call to 
refresh_screen(). As noted earlier, you simply redraw the entire screen because it 
has a simple backgroimd that redraws qmckly. 

The last step starts a timer with a callback to ani n^bal I s to keep the animation 

going, 

Ln 213-23 draw_baMs() is familiar except that it now determines which graphic to draw 
based on the handler for each ball. 

Ln 224-30 ref resh_screen() updates the ball area of the screen by setting the current buffer 
to the frame buffer, redrawing the colored grid, redrawing the balls and then copy- 
ing the frame buffer directly to the screen. 

Ln 232-51 cal cj)os() is familiar except that you now tie gravity to a vector. 

Ln 252-71 calc_pos_.rnd() acts as the new ball "handler." It works like calc_pos() except 
that the acceleration on the ball is random. 

G- Create Separate Module for gravity.c 

File Listing 21-3 shows the code for gravi ty. c, which will be a separate module when the pro- 
gram is compiled. Everything in gravi ty. c should look familiar to or consistent with the rest 
of the tutorial. The four gravity buttons drive this module and the back button exits back to the 
main module. A few additional notes: 

Note that the screen is updated after a button press. Rather than the button redrawing the 
screen after it changed a value, this tutorial uses an nvram callback to do the update. Looking 
back in the game, state file {File Listing 21-1) you will see that both gravi ty_x and gravi ty_y 
include a callback to update_gravi ty(). 

When the main module changes the value of gravi ty_x or gravi ty_y in nvram, it still requests 
the function update_gravi ty, but will not find it since update_gravi ty is in a different module. 
The call is harmlessly ignored and the program proceeds without it. 

H. Make and Compile 

By now the Makefile should look quite familiar. (See File Listing 21-4). Note that you include 
the new gravi ty . c file with the instruction in line 12: 

al I : game, so gravi ty. so 

I. Run the Program 

Make and run the program. 

After the splash screen, you will see a display similar to the previous example, as shown in 
Figure 21-1. There are four new buttons. Remember, Recal I , More Bal I s. Less Bal I s, and Grav- 
i ty. They respond as follows: 

• Pressing More Bal i s adds more balls to the animation loop. 
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1 

2 
3 

4 
5 
6 
7 
8 
9 

10 

11 

12 
13 
14 
15 
16 
17 
18 
19 
20 

21 
22 
23 

24 
25 
26 
27 
28 
29 
30 

31 
32 
33 
34 
35 
36 
37 
38 
39 
40 

41 
42 
43 
44 



i Listing 21-3: gravity.c (sheet 1 of 3) 

#i nc! ude "userapi .h" 

#defi ne SCREEN^WI DTH800 
#defjne SCREEN JE I GHT500 

#define GRAVITY^X350 
#define GRAVITY_Y250 
#defi ne GRAVITY_HW100 
#define MAX_GRAVITY5 

#defi ne SCALE_FACT0R((GRAVITY_HW-1)/(2*MAXJRAVITY)) 
#define CENTER_X(GRAVITY_X + GRAVI TY^HW/2) 
#define CENTER^Y(GRAVI TY^Y + GRAVITY_HW/2) 

voi d i ni ti ai i ze(voi d) ; 
void draw_screen(voi d); 
void up_button(void); 
void down_button(void); 
void left_button(void); 
void nght_button(void); 
voi d update_.gravi ty (voi d) ; 
void draw_gravi ty(void); 
void draw_vector(vo!d); 
double my_sqrt(doubi e a); 

void initial ize(void){ 
draw_screen(); 

} 

void draw_screen(vold){ 
gfx_cl earscr(O); 
gfx_setfont{"georgi a. ttf 48) ; 

gfxJustifystring(0,0,SCREEN_WIDTH,100, "Change Gravity", 

RGB(200, 100, 100), JUSTI FY.CENTER, -1); 
draw_gravity(); 
draw_vector(); 

makebuttom CENTER„X-20, GRAVI TY„Y-50, 40, 40, 

RGB(100, 200, 100), "up_button"); 
makebuttom ("v", CENTER_X-20, GRAVI TY_Y+GRAVI TY_HW+10, 40, 40, 

RGB(100, 200, 100), "down_button"); 
makebuttonl ("<", GRAVI TY_X-50, CENTER_Y-20, 40, 40, 

RGB(100, 200, 100) , "I eft^button") ; 
makebuttonl (">", GRAVI TY^X+GRAVI TY^HW+10, CENTER_Y-20, 40, 40, 

RGB(100, 200, 100), "ri ght_button"); 
makebuttonl ("BACK", 350, 500, 100, 50, RGB(200, 200, 200), "back.button"); 



void up_button(void){ 
int y; 

nv_geti nt(" I nfo. gravi ty_y" , &y) ; 

y--: 

file is Included In the SGOS Installation CD-ROM tutorial file. 
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File Listing 21-3: gravity.c (sheet 2 of 3) 



45 i f (y<-MAX_GRAVI TY) 

46 y = -MAX^GRAVITY; 

47 nv_seti nt (" I nfo. gravi ty_y", y) ; 

48 /* update^ravityO; */ 

49 } 

50 void down_button(voicl){ 

51 int y; 

52 nv^geti nt (" I nfo. gravi ty_y" , &y) ; 

53 y++; 

54 if(y>MAX_GRAVITY) 

55 y = IWVX^GRAVITY; 

56 nv_seti nt (" I nfo, gravi ty_y", y) ; 

57 /* update__gravjty(); */ 

58 1 

59 void left_button(void){ 

60 int x; 

61 nv_geti nt("l nfo. gravi ty_x", &x); 

62 X—; 

63 if(x<-MAX_GRAVITY) 

64 X = -MAX_GRAVITY; 

65 nv_seti nt (" I nfo. gravi ty_x" , x) ; 

66 /* update_gravity(); */ 

67 } 

68 void right_button(void){ 

69 int x; 

70 nv_geti nt (" I nfo. gravi ty_x", &x) ; 

71 X++; 

72 if(x>MAX_GRAVITY) 

73 X = MAX^GRAVITY; 

74 nv_seti nt(" I nfo. gravi ty_x", x); 

75 /* update_gravity(); */ 

76 } 

77 void back_button(void){ 

78 mod_exit(); 

79 } 

80 /* graphic routines V 

81 void update_gravity(void){ 

82 draw^gravi ty () ; 

83 draw_vector () ; 

84 } 

85 void draw_vector(void){ 

86 int g_x, g_y; 

87 char buf[60]; 



This file is included in ttie SGOS installation CD-ROM tutorial file. 
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File Listing 21-3: gravity.c (sheet 3 of 3) 

88 nv^geti nt(" I nfo, gravi ty_x", &g_x); 

89 nv_geti nt(" I nfo, gravi ty_y", &g_y) ; 

90 text_pn ntf (buf , "vec = (%d,%d), |vec| = %g",g_x,g_y, 

91 niy_sqrt(g_x*g_x+g_y*g_y) ) ; 

92 gf x_setf ont ( "georgi a . ttf " ,12); 

93 gfx_drawbar(0, 100, SCREEN.WI DTH, 20, RGB(0, 0, 0)) ; 

94 gfx J usti fystri ng (0, 100, SCREEN_,WI DTH, 20, buf , RGB(255, 0, 0) , 

95 JUSTIFY_CENTER, ~1); 

96 } 

97 factors ***** what is this? ****** 

98 void draw_gravlty(void){ 

99 int center_x, center_y; 

100 int g_x,g_y; 

101 center^x = CENTER^X; 

102 center_y = CENTER^Y; 

103 nv_geti nt (" 1 nfo, gravi ty_x", &g_x) ; 

104 nv„geti nt (" J nfo. gravi ty_y" , &g_y) ; 

105 g_x = center^x + SCALE_FACTOR*g_x; 

106 g_y = center^y + SCALE_FACTOR*g_y; 

107 gfx^drawSdbar (GRAVI TY_X, GRAVI TY^Y, GRAVI TYJW, GRAVI TY_.HW, 

108 0, RGB(200, 200, 255), RGB(200, 200, 255), 2); 

109 gfx_drawbar(center_x-5,center_y-5, 10, 10, RGB (255, 0,0)); 

110 gfx_drawl i ne(center_x, center_y, g_x, g_y, RGB(255, 0, 0) ) ; 

111 } 

112 /* utility function V 

113 double iny_sqrt(doubl e a){ 

114 /* uses newton' s method to find the root of the equation x'^2 - a. 
The roots of this equation are +sqrt(a) and -sqrt(a), 

f(s[n]) s[n+1] = s[n] r(s[n]) 

115 */ 

116 double s; 

117 int n; 

118 if(a<=0) 

119 /* square root of a negative number? */ 

120 /* also, the square root of zero is zero. .. */ 

121 return 0; 

122 s = 1; 

123 for(n=0;n<10;n++){/* 10 loops should be enough */ 

124 s = s - (s*s-a)/(2*s); 

125 } 

126 if(s<0) 

127 s = -s; 

128 return s; 

129 } 

130 

This file is Included in the SGOS instaliation CD-ROM tutorial file. 
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File Listing 21-4: Malcefile file for example6.c 



1 


# Makef i 1 e for the examp! es 


2 


.SUFFIXES: .cpp .c .so 


3 


DEBUG=-g 


4 


SGOS=${shel ! . /I ocate sgos} 


5 


INCLUDE=-I.. -t$(SGOS) 


6 


-co: 


7 


gcc $(INCLUDE) -c -Wall -fPIC -o $@ $< 


8 


. cpp. o: 


9 


g++ $(INCLUDE) $(DEBUG) -c -o $@ $< 


10 


. 0. so: 


11 


gcc -shared -o $@ $< 


12 


al 1 : game, so gravi ty. so 


13 


game. so: exampi e6. o bal 1 „gfx. o 


14 


gcc -shared -o game, so exampi e6.o balf^gfx.o 



This file is included in the SGOS installation CD-ROM tutorial file. 



• Pressing Less Bal I s removes balls. 

• Pressing Remember will store the location, velocity and "personality" of each ball at that 
moment. 

• Pressing Recai I will restore all the balls to their positions and velocities at the time 
Remember was last pressed. This uses nvram to store the data. 

Try pressing Remember, then quit, restart, and then press Recal K Everything should look as it 
did before you quit. Gravity will load the other module (See Figure 21'2\ allowing you to 
change the gravity vector. 




Figure 21-1 - Tutorial: nvram and More Buttons 



Rev: May 2001 




146 



wo 03/023647 



PCT/US02/30286 



21.J-Exercises 



21-16 



Change Gravit\-^ 



vea=(4. 1 X I vecj=4. 1 23 11 



Screen colors are 
changed for readability. 




Figure 21-2 - Tutorial: Screen for Second Module 
J. Exercises 

Try the following exercises: 

1 . Check out the additional tutorial file named exatnpl e6b. c that implements double buflf- 
ering. The animation loop in this example is extremely flexible. You can probably 
already see ways to change it. To see how this example would run without double buff- 
ering, comment out the 1st, 4th, and 5th lines of refresh_screen() so that you draw 
directly to the screen all the time. Notice the flashing. 

2. Also try these adjustments: 

• Make the saved ball position appear when the game is started. 

• Make nvram continually store the ball positions. 

• Create other ball "handlers." 

3. Make another module to modify some other parameter, e.g. background pattern or the 
randomness of the cal Ijos^rndO. You will need to add some nvram variables to do 
this. After you change the game, state file, delete the nvram file to force SGOS to rein- 
itialize the nvram. You then need to trap on this and initialize the nvram yourself. 
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V. GAME ENGINE TUTORIAL 

Chapter 22 - Build a Simple Game22-1 
Chapter 23 - Build a 9-Line Game 
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Chapter 22 — Build a Simple Game 



[Put example using generic template here ] 
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Chapter 23 — Build a 9-Line Game 



A. Use the 9tLine Game Template 

When available 
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VI. HARDWARE SOLUTIONS 

Chapter 24 - Hardware Solutions24-1 
Chapter 25- Online Gaming Architecture (olga) 



Rev: May 2001 ^.^ Shuffle Mastei j 



151 



wo 03/023647 



PCT/US02/30286 



Chapter 24 — Hardware Solutions 



A. Game Main Module 

The tutorials in IV, API TUTORIAL include several examples of using the userapi calls. 

In some cases the Linux and SGOS software may be preinstalled on hardware provided by 
Shuffle Master. You may be using PC/104 or other hardware specified by Shuffle Master for a 
single install to a target machine. 

A hardware solution currently available from Shuffle Master is as follows: 
[add details ] 

1. URGENT Platform 

2. CHIMP — main module ( 

3. HABIT -interface between hardware (lamps, switches, etc.) and computer; includes 
four serial ports 

4. PC/104 Electronics Stack, includes: 

2 a. HIC PC/ 104 Module - (if faulty, lights and buttons will not work, or game may not 
come up) 

b. Static RAM PC/104 Module - (if faulty, get static RAM error on screen) 

c. Operating System PC/104 Module, includes: 

Ml — M4 are operating system - (if faulty get no operation) 

M6 is the game personality module - if bad get no game or security violation 

Newer systems will have a different PC/104 stack, with just two consolidated components. 
The new HIC module will add SRAM functionality, eliminating the second module. Shuffle 
Master will provide configuration and installation instructions. 

Contact Shuffle Master for currently available and recommended main module hardware. 

B. Other Supported Hardware 

SGOS includes drivers for the following commonly used hardware. Refer to vendor documen- 
tation for configuration and installation. 

1. Touch Screen Driver 

Microtouch 

2. Bill Validator Driver 

JCM serial and pulse types (or other manufacturers with same protocols) 

3. Coin Head Driver 
Asai Seiko CC46 



Rev: May 2001 




152 



wo 03/023647 



PCT/US02/30286 



24,C- Mechanical Reels 24-2 

4. Coin Hopper Driver 

Asai Seiko Hopper Driver 

5. Serial Protocols 
a, IGT SAS 402 
a. Bally SDS 

6. Additional Drivers 

Contact Shuffle Master for drivers for other hardware solutions. 

C. Mechanical Reels 

retrofits or new 
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Chapter 25 — Online Gaming Architecture 

(olga) 

A. Networking Protocols 

Refer to Appendix 
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APPENDIXES 



Appendix A - Linux Setup Considerations 
Appendix B - mafce and the Makefile 
Appendix C - Embedded userapi Calls 
Appendix D — .oti Configuration File 
Appendix E - [yourgamej.state File 
Appendix F- Generic Game Template File 
Appendix G — Graphics Conversion Tool Listing 
Appendix H- l\/lakestrips Utility (9 Line Games) 
Appendix I - Nine Line Game Template 
Appendix J — Poker Game Template 
Appendix K- Other Templates 
Appendix L - Online Protocol Exception Codes 
Appendix M — Screens for Setup and Recordkeeping 
Appendix N - Advantec Hardware Solution Information 
Appendix O - Further Help and Troubleshooting 
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Appendix A - Linux Setup Considerations 



1. General Notes 

Although C programming can be done in Windows and then copied to Linux, it will be sim- 
plest to work directly with SGOS m Linux. You can install Linux most easily on a desktop 
PC, but a laptop is also an option. Laptops often use specialized hardware, so finding proper 
Linux drivers can be more difficult. 

The steps to set up SGOS on the development computer depend on your exact situation: 

2. If Linux Is Already Loaded 

If you already have Red Hat Linux 6.x loaded on your computer, you can go ahead and install 
SGOS from the provided CD-ROM . 

3. Installing Linux on a Dedicated Computer 

Linux can function well on an older Pentium computer with 32MB of RAM (64 is better). A 
dedicated computer will simplify the installation. 

4. Sharing with a Windows Computer 

To install Reid Hat Linux alongside Windows on an existing computer requires a dedicated 
hard drive or a dedicated drive partition. 

Once again Linux requirements are economical. To keep things simple, install a separate drive 
if possible. An outgrown 2 or 3 GB drive from a Windows computer will be quite sufficient for 
game development with SGOS. 

5- Using the Shuffle Master Development System 

Shuffle Master offers a turnkey hardware and software unit for development with SGOS. 
These units ship with the appropriate software loaded. 

6. Additional Help 

If you are a novice with Linux — and especially if you will have a dual boot system with both 
Windows and Linux — pick up one of the many Red Hat Linux books available. For example. 
Red Hat Linux for Dummies gives a good explanation of dual-boot systems and how to resolve 
common problems. You will also find abundant help on the internet. Three helpful sites are 
linuxcare.com, supporLcom, and questionsexchange.com. 
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Appendix B - make and the Makefile 



1. Overview 

sake is a Linux tool to organize, update, compile and link the files that make up your program. 
When you run make it looks first for a file called nakef 1 1 e to tell it about the dependencies in 
your program files. If it does not find nakef i I e, it next looks for a ilakef i I e. SGOS is set up to 
use the one with an upper case "NT', so it stands out in the listings. The Makefi I e is basically a 
set of rules to tell make precisely how it should construct non-source files firom other files so it 
can build and install the entire program. 

Each time you run make (by typing make at the command line), it will check which source files 
have changed and update every affected file in your project. Once it is set up correctly, the 
Ilakef i I e fully maintains your files. Any time you change source code, invoking nake will 
immediately rebuild your project. 

SGOS includes a Ilakef i I e for each game template and for each tutorial. The tutorial Make- 
files are more simple than the example which follows, but every Makefile includes the same 
basic steps. If you are new to Linux (Ilakef 1 1 e is originally a Unix tool, adapted to Linux), it is 
worth spending some time getting to know the Makefile structure and rules. This manual can 
get you started with the nake tool as it is used to build games with SGOS templates. The nake 
tool and the Makefi I e offer many very complex and powerful options. Picking up a good 
Linux manual is highly recommended, 

2. A Makefile Example 

A breakdown of the Makefile for the Press Your Luck 9-line game (File Listing C-1) is as fol- 
lows: 

Line 2: .SUFFIXES: .cpp .0 .so tells make the list of known suffixes for files in the direc- 
tory that it needs to use in this makefile. 

Line 3: DEBUG=-g is used as a compiler flag. It tells the compiler to generate debugging 
symbols. See Chapter XXX for more on debugging your game in the SGOS. 

Ln4-8: The following lines define some variables SHARED, ENGINE, SGOS, LIBS and 
I NCLUDE, find the path to userapi . h and all of its associated SGOS libraries and 
include the path as a string command line option to the compiler. 
SHARED=${shel I ./locate shared} 
ENGINE=:${sheil ./locate engine} 
SGOS=${shell ./locate sgos} 
LIBS=-L$(SHARED) 

INCLUDE=-I.. -I$(SG0S) -l$(SHARED) -l$(ENGINE) 

Line 9: SRCS=$(shel I I s * . c) finds all the . c files n the directory and assigns them to the 
variable SRCS. 

Line 10: TARGETS=$(SRCS: . c=. so) changes the suffix of all the . c files in SRCS to . so. and 
assigns them to the variable TARGETS. 
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File Listing B-1 : sample Makefile listing 

1 # Makef i 1 e for ni nei i ne 

2 .SUFFIXES: .cpp .c .so 

3 DEBUG=-g 

4 SHARED=${shel I . /I ocate shared} 

5 ENGI NE=${5hel ! ./locate engine} 

6 SGOS=${shel I . /i ocate sgos} 

7 LIBS=-L$(SHARED) 

8 iNCLUDE=-l.. -1$(SG0S) -l$(SHARED) -l$(ENGINE) 

9 SRCS=$(shell Is ''.c) 

10 TARGET$=$(SRCS: . c=, so) 

11 GAMEOBJECTS=ni nel i ne. o pyl jQfx. o 

12 .c.o: 

13 gcc $(INCLUDE) -c -Wall -fPIC -o $@ $< 

14 . cpp, o: 

15 g++ $(INCLUDE) $(OEBUG) -c -o $@ $< 

16 .o.so: 

17 gcc -shared -o $© $< 

18 all: game. so $ (TARGETS) cleanup 

19 game. so: $(GAHEOBJECTS) 

20 gcc -shared -o game. so $(GAMEOBJECTS) $(LIBS) -I engine -Inineline 

21 1 ast^ames. so: last_games.o lastgame_gfx.o 

22 gcc -shared -o I ast_games. so last_games.o I astgame^gfx. o $(LI8S) -i last- 
games -Mastnine 

23 bonus. so: bonus. o bonus^gfx.o 

24 gcc -shared -o bonus, so bonus, o bonus_gfx.o 

25 paytabte.so: paytable.o pay_gfx.o 

26 gcc -shared -o paytabte.so paytable.o pay^gfx.o 

27 cl eanup: 

28 rm -f ninellne.so debug* 

29 cl ean: 

30 rm -f *.o *.so nvram debug.* core 

31 sos: 

32 ©echo "Enter ROOT password to build app image..." 

33 esu -c ./makesos 

34 # Game Dependencies 

35 bonus. o: bonus. c bonus_gfx.h 

36 game_books. o: game_books. c 

37 * help.o: help.c 

38 I ast^games. o: iast_garaes.c i astgame^gfx. h nineline.h 

39 ni nel i ne. o: ni nel i ne. c pyl _gfx. h ni nel i ne. h 

40 paytable.o: paytable.c pay„gfx.h nineline.h 

This sample listing is from the Press Your Luck nine-line game. 
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Ln 14-17: 

Line 18: 
Line 19: 
Line 20: 

Ln 21-22: 
Ln 23-24: 

Ln 25-26: 



GAIIEOBJECTS=ni nel i ne. o pyl _gfx. o associates the files ni ne! i ne. o and pyl .gfx. o 

to the variable GAMEOBJECTS. 

. c. o: is a generic rule for creating .o files from •€ files, 

gcc $(INCLUDE) -c -Wall -fPIG -o $@ $< defines the generic rule, as follows: 

This line must begin with a tab to be recognized by make as a command by the gcc 
C compiler. 



•c compiles each source file to an object file, but does not link, 

•lllal I warns about all questionable constructs. 

fPI C turns on position independent code. This option is necessary. 

■0 $@ places the output in the file $« (shorthand for the name of the target, expands to 



: is shorthand for the name of the input file (expands to f 1 1 e. c). 
.cpp.o: 

g4^+ $(INCLUDE) $(DEBUG) -c -o $@ $< 
.o.so: 

gcc -shared -o $@ $< 

, cpp, o and . o. so give general rules for turning C++ files into object files, and for 
turning object files in shared object files. 

a! I : game, so $(TARGETS) cl eanup states that to make everything, make must cre- 
ate game, so from all the . so's in TARGETS and execute the cl eanup. 

game, so: $ (GAMEOBJECTS) states that game.so is dependent on GAMEOBJECTS, which 
expands into a list of files. 

gcc -shared -o game.so $(GAME0BJECTS) $(L1BS) -I engine -ininel inemakes a 
shared object out of GAMEOBJECTS, LI BS, links in the engi ne and ni nel i ne libraries, 
and names it game, so. 

The next two lines state that I ast_games. so is dependent on last_gaffles.o and 
I astgame^gfx. o. It makes the shared object 1 ast_games. so. 

I ast^games. so: Iast_games.o lastgame^gfx.o 

gcc -shared -o last_ganes.so last_:games.o lastgane^fx.o $(LIBS) -I last- 
games -I lastnine 

The following lines state that bonus, so is dependent on bonus, o and bonus_gf x. o. 
They make the shared object bonus, so. 

bonus. so: bonus. o bonus^gfx.o 

gcc -shared -o bonus. so bonus. o bonus„gfx.o 

The following lines state that paytable.so is dependent on paytable.o and 
pay_gfx. o. It makes the shared object paytab! e. so. 

paytable.so: paytable.o pay^gfx.o 

gcc -shared -o paytable.so paytable.o pay__gfx.o 

The next two lines remove the ni nel i ne. so file and all debug files. The rm remove 
command has the -f forced option, so there will be no asking for confirmation. 



$ (INCLUDE) provides the path to userapi.h found above. 



file.o). 
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Ln 27-28: cl eanup: 

rn -f nineline.so debug* 

Ln 29-30: The following lines act the same as those above but they remove all objects, shared 
objects, nvraa, debug files and any core dump files that may exist. 

clean: 

rm -f *.o *.so nvran debug.* core 

Ln 31-33: The following lines will start the script that makes the shared objects for the disk 
oh chip. You must be super user, and will be prompted for the password. 

sos: 

eecho "Enter ROOT password to build app Inage. .." 
esu -c ./oakesos 

Ln 35-40: The following lines show the associated dependencies for the object files on the . c 

source and . h header files. 

bonus. o: bonus. c bonus_gfx.h 
game.books . o: game_books . c 
help.o: help.c 

i ast^ganes. o: last_gaines.c I astgaraejfx. h nineline.h 
ni nel i ne. o: ni nel I ne. c pyl _gfx. h ni neli ne. h 
paytabi e. o: paytab! e. c pay^gfx. h ni nel t ne. h 

3. Running Make 

To create the game, so file, type 
make 

To use this makefile to delete the executable and object files fi*om the directory, type 
make clean 

To rebuild the entire program (recompile and link all objects, not just the time stamped ones) 
type 

make a! 1 

To create so's for use in making the Disk On Chips, (as root) type 
make sos 
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1- General Notes About USERAPI Calls 

userapi . h declares functions for graphics, sound, timers, and several other game operations. 
They are a versatile set of functions for graphics, widgets, module handling, timers, nvram 
access, soimd, hardware interface, text formatting, system calls, multigame manamgment and 
miscellaneous routines. 

The tutorials in JV. API TUTORIAL include several examples of using the userapi calls, 

2. Graphics Routines 

The graphic routines have a few conventions for describing rectangles and colors. Rectan- 
gles are defined by the 4-tuple (x, y, «r, h), where (x, y) is the location of the upper left cor- 
ner and (w, ti) is the width and height of the rectangle. Colors are specified using integers, 
which represent an RGB triple. The macro RGB(r, g, b) in userapi . h converts RGB values 
to their corresponding integer, R,G,B are in the range 0 and 255. 

The API graphics functions can interact with one of the three SGOS buffersThis context 
gets set by gfx_setcontext. Discussion in Chapter 7 reviews the relevant contexts for 
each function. They are: 

• GFX.SCREENBUFFER 

• GFX_BACKGROUNDBUFFER 

• GFX_WORKBUFFER. 

The transform flags are: 

• GFX_FLIP_HORIZ 

• GFX_FLIP_VERT 

• GFX_R0TATE_90 

• GFXJOTATE^IBO 

• GFX_R0TATE_270 

The transforms are applied in the following (arbitrary) order: 
image ct> flip horizontat^flip vertical llO rotates cO result 

The text justification flags are: 

• GFX_JUSTIFY_HORIZ^CENTER 

• GFX_JUSTIFYJORIZ„LEFT 

• GFX_JUST!FYJORIZ_RIGHT 

• GFX_JUSTIFY_VERUENTER 

• GFX„JUSTIFY„VERT„TGP 

• GFXJUSTIFY_VERT_BOTTOII 

• GFX_JUSTIFY_CENTER 
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gfx_cl earbuf fer(i nt col or) 

Clears the entire buffer with colon 

gfx_copybuffer(int x, int y, int w, int h, int destx, int desty, int 
srcbuffer, int destbuffer) 

Copies the box specified by x,y,w,h firom the source buffer to the destination buffer at 
destx, desty. 

gfx_draw3dbar(int X, int y, int w, int h, int fill, int ul^fill, 
int lr_fill, Int bdwidth) 

The rectangle is at x, y, h. f i 1 1 , ul _f 1 1 1 , and I r_f i ! I are colors. The color of the cen- 
ter of the rectangle is f i 1 1 , Passing a -1 for f i 1 1 indicates a transparent center, allowing 
you to draw a fi-amed rectangle, ul _f 1 1 1 is the color of the upper and left sides of the rect- 
angle; I r_f i 1 1 is the color of the bottom and right sides. 

gfx_drawbar(int x, int y, Int w, int h, int c) 

Draws a solid rectangle at x, y with width % height h, and color c. 

gfx_drawicon(int type, int x, int y, void ^bitmap, int trans_color, int 
xoff, int yoff, int w, int h, Int transform) 

*** add type info etc. when done 

Draws the bi tmap on the active buffer with the upper left comer at x,y. xoff and yoff are 
the offsets in the image of the cropped rectangle, w, h are the width and height of the rect- 
angle and transform is the orientation ( 0, 90, 180, 270). . 



TIP... Passing -1 for both the x and y loads the entire bitmap but suppresses the 
drawing. This provides a way to cache an image in memory. 



gfx.drawi i ne(i nt x1 , i nt y1 , i nt x2, i nt y2, i nt c) 

Draws a line 1 pixel wide firom the point x1 , y1 to the point x2, yZ with color c. 

???gfx_drawpixel (int x, int y, int c) is this still here do we use draw- 
I ine cal I 

Draws a pixel at x,y the color c. 

???is this drawsprite or drawbitmap since we are passing in the type^ 
what are the valid types also ... 

gfx__drawsprite (int type, int x, int y, void *bi tmap, int xoff, int yoff, 

int w, int h, Int transform) 
Similar to gfx_drawi con(), except bitmap must use color 99 as the transparent color. 

int gfx_drawstring(lnt x, Int y, int w, Int h, int transform, char* str, 
int color, int justification, int bgcolor) 

Writes a zero-terminated string str to the buffer, x, y is the lower left comer of the string, 
transform is 0, 90, 180, or 270, color is the text color, justificaiton desired, and 



♦ « 

"•■V 
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bgcol or is the background color. Passing -1 for bgcol or makes the background to be 
transparent. Note that gfx_drawstrlng() can handle new line characters (\n). 

gfx__geticondiinensions(void *icon, Int *w, int *h) 

Returns the w and h of he specified bitmap. 

??? is this supposed to be in here??? 

gfx_getrect(i nt x, int y, int int h, void *buf) 

This routine copies the entire rectangle x, y, w, h, of the specified buffer. 

gfx_setcachesize(int size) 

Sets the current cache size in megabytes used for graphics. 

gfx_setcaching(int onoff) 

Sets the use of the cache on or off for graphics. 

gfx^setcl i ppi ng(i nt onoff) 

Sets automatic graphics clipping on or off. 

gfx_setcl ippingrect(int x, int y, int w, int h) 

Sets the current location and size used for clipping. 

gfx_setcontext(i nt context) 

Sets the current graphics context context is one of the following values: 

• GFX„SCREENBUFFER 

• GFX.BACKGROUNDBUFFER 

• GFXJORKBUFFER 

All commands, unless specifically stated, work the same whether drawing to the screen 
(GFX.SCREENBUFFER) or drawing to memory (GFXJACKGROUNDBUFFER, GFXJORKBUFFER). 
There is video clipping provided for each buffer. 

gfx_setfont(char* fontfile, int size) 

Loads the font in the file fontf i I e, and makes it the current font. Sets the current font size 
to size. 

3. Widget Routines 

*** This entire section is changing. We will speicify default atrtributes and then use MAC- 
ROS to modify those. 

SGOS buttons respond to finger presses on a touchscreen. For the development system on 
your desktop computer you can activate a button with a mouse. Each button calls a call- 
back function when pressed. These callback functions may have one argument which is 
the name of the button pressed. This allows many buttons to have the same callback func- 
tion, which is useful when putting keypads, or other similar controls on the screen. 

* While there is only really one kind of button, there are three ways to make it The sim- 
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plest way to make a button is to give it a color and a name. The name is then displayed on 
the screen. The second way to make a button is to associate an icon (or graphic) with it; 
the icon is then displayed on the screen instead of the button name. The third way is to 
pass two icons, one for the button as it normally is and one for when the button is pressed. 

* You can change the parameters of a button by referring to it by name, 
wi dget^acti on(. . . ???) 

wiclget_draw(char *name) 

widget__getattribute(char *name, char * attribute, int *value) 
widget_inake(int type, char *naine, int int y, int w, int h) 
wldget_setattribute(char *narae, char *attribute, int value) 

4. Module handling routines 
mod_exit(void) 

Fetches the library name most recently saved by mod_load(), and does a mod^umpO to it. 
mod__exi t() also removes the library name from the saved list. 

modj unip(char *mod_name) 

Just like raod_l oad(), except the current library name is not remembered, 
mod_l cad (char "^mod^name) 

Loads the library mod.name, and puts a request for the function Initial I ze() m the event 
queue. inod_load() also saves the current library name for retrieval by mod_exi t(). 

5. Timer ROUTINES 

timer_start(long timeout, char* callback) 

starts a timer of duration timeout in milliseconds. When the timer expires, a request for the 
function cal I back is put in the event queue, cal I back is a string giving the function name. The 
callback function must be passed without arguments, 

ti mer^ki 1 1 (char* cal I back) 

Deletes all the timers having the callback function cal I back. The function named cal I back is 
not called. 



6. NON-VOLATILE RAM ROUTINES 

The nvram is managed by a set of special routines. The game application never directly 
touches an>11iing in the nvram; all game manipulations of the nvram occur through these fiinc- 
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tions- The nvram is partitioned into variables by the nvram manager according to the contents 
of the nygame. state file. This text file looks similar to a list of C structure declarations, except 
the comment character is a # and this line never passes through a parser. The nvram parser 
reads this file at startup. 

The mygame. state file makes it easy to put variables in the nvram, since the game application 
never needs to be concerned with the offisets of variables in the nvram. Structure definitions 
can even be nested. 

An nvram string refers to a specific variable in nvram. A typical one looks like Game.cred- 
itsleft. To allow access to arrays, standard printf-style format characters can be put in the 
string, and the values to insert are supplied as the additional arguments on each line. This fea- 
ture allows strings like Hi story bet. Stats, icon or even BiliHis-- 
tory[%l ] . date[%l ] . More elaborate formats are also possible, such as HyStruct. %s[%l ] , since 
the string is formatted before being parsed. 

The following set of procedures sets an nvram variable to the passed value. Use the variant 
that matches the data type of the nvram variable. The additional arguments are the nvranstr 
formatting values, if needed. 

nv_setchar(char* nvramstr, char, ...) 
nv.setdoubl e(char* nvramstr, doubi e, . , . ) 
nv_setfloat(char* nvramstr, float, ...) 
nv_set! nt(char* nvramstr, int, ...) 
nv_setl ong{char* nvramstr, long, -..) 
nv_setshort(char* nvramstr, short, ...) 

The following functions retrieve a value fi-om an nvram variable. The value is returned 
through the pointer val . The function itself returns nothing. Use the variant matching the data 
type of the nvram variable. The additional arguments are the nvramstr formatting values, if 
needed. 

nv_getchar(char* nvramstr, char* val, .,.) 
nv_getdouble(char* nvramstr, double* val, ..,) 
nv_getfloat(char* nvramstr, float* val, ..,) 
nv_geti nt(char* nvramstr, i nt* val , . . , ) 
nv_getl ong(char* nvramstr, long* val, ,..) 
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nv^etshort(char* nvramstr, short* val, ...) 

The following routines increment an nvram by amt, char* may be negative. No values are 
returned. Use the variant matching the data type of the nvram variable. The additional argu- 
ments are the nvramstr formatting values, if needed. 

nv_i ncchar(char* nvramstr, char amt, , , . ) 
nvJncdouble(char* nvramstr, double amt, .,.) 
nvj ncf I oat(char* nvramstr, float amt, ..,) 
nv_i nci nt(char* nvramstr, i nt amt, • . . ) 
nvJnclong(char* nvramstr, long amt, .,.) 
nvj ncshort(char* nvramstr, short amt, ...) 

7. Sound ROUTINES 

sound jjl ay (char* file, Int channel, Int loop, int pan) 

Plays the sound file named char* f i I e. 

• i nt I cop is either 0 or 1. 0 plays once; 1 starts a loop which ends with a call to 
sound_stop(). 

• i nt channel sets the sound to one of the 32 available channels. 

• i nt pan ranges from -2 to 2, where -2 is left, 2 is right speaker. 

sound_stop(int channel) 

Stops the sound currently playing in the specified channel, 1 through 32. 
sound_volume(int percent) 

Sets the sound volume to percent percent of maximum volume. 

8. Mechanical Reel Routines 

reel _spin (unsigned char* reel stop, int numstops) 

Initiates the spin of the mechanical reels, and stops those reels at array reel stop, values 0-21, 
for the number of reels numstops, default value 3. 

reel s^stop (unsigned char reel mask) 

Stops all spinning reels from reel mask. Can be used for a skill stop. 
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9. External Display Routines 

extdisp_award(char* AwardChar) 

Displays the award to the external display. 

extdi sp_bet(char* BetChar) 
Displays the bet to the external display. 

extdi sp_credi ts(char* Credi tsChar) 

Displays the credits to the external display. 

extdi sp.get(int type, char* DispString) 

Reads the currently displayed text string from the external display of type into Di spStrl ng. 
extdi sp_set(int type, char* DispString) 

Sends the string Di spStri ng to the external display of type. Supported external display types 
defined in userapi . h are: 



10- Text Formatting routines 

i nt text j)ri ntf (char* str, const char* format, . . . ) 

Prints format, with any additional variables, into the buffer pointed to by str. This function 
does not allocate any memory for the string. 

int text_strcat(char* dest, const char* src) 

Concatenates a copy of src to dest, src is untouched by this operation. 

int text_strcinp (const char* strl, const char* str2) 

Alphabetically compares strl and str2 and returns an integer based on the outcome: 



LED_DI SPLAY 



Value 



Meaning 



Less than zero 



strl is less that str2 



Zero 



strl is equal to str2 
strl is greater than str 



Greater than zero 



11. Resource routines 



These resource functions ... 



resource_get(char *\«hat. 



resource__set„f 1 1 e„opt(char *base_naine, i nt inust_exl st) 
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This is usually used through the #defined ftintion resource-set_file(base_name). 

Notes: Strings returned are sopied into the buffer given, THe strings are guarenteed not to be 
longer that RESOURCE_MAXSTRLEN bytes long. 



12. Miscellaneous routines 

These miscellaneous functions do not fit in any of the above categories. 
sys_breakpoint(int tag, void* param) 

Since the debugger will not allow breakpoints to be set in the game code (because the game is 
technically a "library"), calling this function in your game code cleverly allows you to trap 
breakpoints in the debugger. Passing a pointer in the argument param allows you view and alter 
a game variable in the debugger. The fimction sys^breakpoi nt is listed below for reference: 



void sys_breakpoint(int tag, void* parain){ 
char char_setval = -1; 
short short_setval - -1; 
int int^setval = -1; 
if (char^setva! != -1) { 

char* p = (char*)parain; 
*p = char_setva!; 

} 

if (short_setval != -1) { 

short* p = (short*)parain; 
*p = short_setva! ; 

} 

if (int„setvai != -1) { 

int* p = (int*)param; 
*p = i nt_setval ; 



sys_debug(char* format, ...) 

Prints format, which may contain pri ntf-style formatting characters, to the file debug, out. 
sys_exec(char* func) 

Executes the function func and returns NULL if the function does not exist, func is a string giv- 
ing the function name. 

unsigned long rnd_get_number (unsigned long range) 

Returns a random number "r" such that 0 <= r < range. 

sys_setl amp(char * light, int state) 

Sets light I i ght to state. 1 i ght is a string defined in the . oti file. 

unsigned long sys^clockQ 

Returns the system clock time. 



> 
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char* sys_getreleasedate(void) 

Returns a string stating the release date of the running version of SGOS, 

char* sys_getversion(void) 

Returns a string stating the running version of SGOS. 

char* sys_getversi on(voi d) 

Returns a string stating the running version of SGOS. 

13. ENGINE API Calls 

The following API calls become available by including engi ne^api . h in the Makefile: 
#define TYPE^SOLO 0 
#define TYPE^BULTI 1 

A. Credit Engine Data 

engine_changebet(int change) 
Change is in (+/-) units of bet i no 

long engi ne^etaward (void) 

Returns the current total amount won. 

I nt engi ne_getbet(voi d) 

Returns the amount of the current bet. 

i nt engi ne^getbeti nc (voi d) 

Returns the value of the bet incrementor. 

I ong engi ne^getcredt ts(voi d) 

Returns the current number of credits on the machine. 

char engi ne_getdoorcl osedf I ag(voi d) 

Returns the status of the door closed flag, 1 closed, 0 open 

long engi ne_gethandpay (void) 
Returns the handpay amount. 

long engine _getpaid(void) 

Returns the current amount won. 

long engi ne.jetpaidout (void) 

Returns the amount collected from hopper. 
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char engine_^etpowerresetflag(void) 

Returns the status of the power reset flag: 1 power reset, 0 not. 

char engi ne_getrebet(voi d) 
Returns the rebet flag value. 

engine_setbetinc(int new_betinc) 

Set the new bet incrementor, in credits. 

engi ne_setsnap(voi d) 

Sets a snap for the credit countdown, 

B. Managing a Multigame 

char game_getcurrentstate(voi d) 

Returns the current game state. 

int game_getdenomi nation (void) 

Returns the amount of the current denomination. 

i nt game^getmaxbet (vo i d) 

Returns the current naxbet amount of the machine 

i nt game_i nprogress (vo i d) 

Returns status 1 if a game is m progress, or 0 on false. 

game.l oad(char ^^^name) 

Sets currentgame to active instance of name and loads the I i b 

game.regi ster(char *naine, int denom, int maxbet, int percent, char type) 

gaine_setcurrentstate(char state) 
Sets the game state to state. 

game_setdenomi nation (int denom) 

Sets currentgame to currentgame name with denom 

C. Miscellaneous 

char * text J convert (int num, int pad) 
char * textj convert (long num, int pad) 

char reel _isstopped( int reelnum) 

Returns the state of reel (1...5) 
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14. Game Specific API Calls 

A. Nineline Games 

The following API calls become available by including ni nel i ne_api . h in the Makefile: 

char getbetperl i ne(voi d) 

Returns the current bet per line. 

char getLinesBet(void) 

Returns the number of lines that have bets placed 

B. Poker Games 

The following API calls become available by including poker_api , h in the Makefile 
(empty for now) 
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Naming of . oti and . state files is derived from the base name given in the API call Regi s- 
terGameO . If your application has multiple games, each game will have its own . oti file. Mul- 
tiple denominations for the same game will share the same . oti file, 

1. MYGAME.oTi File Listing 

You will modify the default - oti file for your game's hardware, if different. For instance, an 
extra button on the target machine will require a related mapping. 

Refer to parts B and C of this chapter for more about . oti syntax and file addresses. 

The following is an example of a typical .oti file. Make changes as needed for your game 
configuration. 

1 # Shuff I e Master Tempi ate OTI f i I e 
2 



19 2, bi 1 1 acceptor; 

20 3, protocol; 

21 4, watchdog; 

22 } 

23 debug : { 

24 output : f i I e; 

25 options : {all ;} 

26 } 

27 nvram : { 

28 media : file; 

29 } 

30 kernel : { 

31 "snd-card-es1688.o sndjrq=9"; 

32 } 

33 output : { 

34 <3,2>, LOCKOUT; 

35 <3,5>, HOPPERMTRL; 
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3 ##################### 

4 # Begin OTI Data # 

5 ##################### 

6 runtime : { 

7 load : game; 

8 } 

9 startup : { 

10 di spl ay; 

11 sound; 

12 touchscreen; 

13 chimp; 

14 bi 1 1 acceptor; 

15 protocol; 

16 } 

17 serial : { 

18 1, touchscreen; 
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36 
37 
38 
39 
40 



74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 



<3, 6>, 
<3,7>, 
<2, 6>, 
<3, 0>, 



HOPPEi^RH; 
MUTESWITCH; 
DIVERTERA; 
DIVERTERB; 



41 


portmap 


: { 






42 


<P, 


4, 




z. 


mai n_open; 


43 


<Rc 


4, 


o>. 


a. 


mal n_cl osed; 


44 


<P, 


4, 


1>, 


c. 


1 ogi c_open; 


45 


<R, 


4, 


1>, 


d. 


I ogi c_cl osed; 


46 


<P, 


4, 


2>, 


A, 


hopper_cl osed; 


47 


<R, 


4, 


2>, 


1, 


hopper_open; 


48 


<P, 


4, 


3>, 


s. 


pri nter_cl osed; 


49 


<R, 


4, 


3>, 


X, 


pri nter_open; 


50 


<P, 


4, 


4>, 


s. 


cash_cl osed; 


51 


<R, 


4, 


4>. 


X, 


cash_open; 


52 


<P, 


4, 


5>, 




drop_cl osed; 


53 


<R, 


4, 


5>, 


c. 


drop_open; 


54 


<P. 


3, 


o>. 




, coi ndn_switch; 


55 


<R, 


3. 


o>. 


k! 


coi nup„swi tch; 


56 


<P, 


2, 


2>, 




' , coi nrev_swi tch; 


57 


<P, 


3, 


2>, 


1, 


hopperup_swi tch; 


58 


<R, 


3, 


2>, 




, hopperdn_swi tch; 


59 


<P, 


3, 


6>, 


0, 


hopperful I up_swi tch; 


60 


<R. 


3, 


6>, 




hopperful 1 dn_swi tch; 


61 


# The, following are synthesized 


62 


<$, 


0, 


o>. 


f. 


bi 1 l„clear; 


63 


<s, 


0, 


1>, 




bi i l_error; 


64 


<s, 


0. 


3>, 




pri nter_cl ear; 


65 


<S. 


0, 


4>, j. 


bi i 1 up_swi tch; 


66 


<S, 


0. 


5>, 


m, 


bi 1 1 dn^swi tch; 


67 


<s. 


0. 


6>, 


w. 


bi 1 1 1_swi tch; 


68 


<s, 


0. 


7>, 


e, 


bi 1 1 2_swi tch; 


69 


<s, 


1, 


0>, 


r. 


bi 1 1 5_swi tch; 


70 


<s 


1. 


1>, 


t. 


blll10_switch; 


71 


<s 


1. 


2>, 




bi 1 1 20_swi tch; 


72 


<s 


1, 


3>, 


u. 


bi 1 1 50_swi tch; 


73 


<s, 




4>, 


1 , 


bi 1 1 10Q_swi tch; 



events! 



} 

panel 
<P 



<P 



{ 

.7>, 
1>, 



2, 
3, 

<P, 0, 3>, 
<P, 0, 5>, 

<P,0, 7>, 

<Pr1.1>, 

<P,1,3>, 
<P,1,5>, 
<P,1,7>, 
<P, 2, 1>, 
<P, 2, 3>, 
<P, 2, 5>, 
<P, 0,1>, 
<P, 0, 2>, 



1, service_switch, switch_1 

2, col I ect_swi tch, swi tch_2 

3, betonel i ne_swi tch, swi tch_3 

4, betthreel i ne_swf tch, swi tch_4 

5, betf i vel i ne_swi tch, swi tch_5 

6, betsevenl i ne_swi tch, swi tch_6 

7, betni nel i ne_swi tch, swi tch_7 

8, betlperline.swi tch, switch_8 

9, bet2perl i ne_swi tch, swi tch_9 
0, betSperl i ne_swi tch, swi tch_10; 

' - ' , bet4perl i ne_swi tch, swi tch_1 1 
* =' , betSperl i ne_swi tch, swi tch_12 
' ] ' , spi n„swi tch, swi tch„1 3 

' ; ' , setup_swi tch, swi tch_1 4 
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90 <P, 0,0>, V, j ackpot_swi tch, switch„15; 

91 } 

92 lights : { 

93 #These I i ght stri ngs are used by the engi ne 

94 <0,0>, toweralight; 

95 <0, 2>, towerblight; 

96 <0, 4>r toward i ght; 

97 <2, 7>, servi eel i ght; 

98 #These I i ght stri ngs are user defl ned 

99 <0, 1>, spinfight; 

100 <0, 3>, playllight; 

101 <0, 5>, playSlight; 

102 <0,7>, playSlight; 

103 <1,1>, playTMght; 

104 <1,3>, play9light; 

105 <1,5>, betl light; 

106 <1,7>, bet2nght; 

107 <2,1>, bet3light; 

108 <2,3>, bet4light; 

109 <2,5>, bet5light; 

110 <3, 1>, col I ectl i ght; 

111 } 

112 coordinates : { 

113 # These are 'shared' widgets used fay the engine 

114 creditbox : 5,500,70,30; 

115 infobox : 400,475,400,20; 

116 paidbox : 270,500,70,30; 

117 betbox : 620,500,50,30; 

118 payoutbox : 110,500,125,30; 

119 powerreset : 10,70,100,10; 

120 doorclosed : 700,70,100,10; 

121 win-a : 200,60,400,20; 

122 win-b : 180,470,100,20; 

123 # Any * custom' widgets should go here... 

124 linesbox : 460,500,50,30; 

125 betperl i nebox : 540,500,50,30; 

126 } 

127 inf ©strings : { 



128 


GOOD LUCK; 


129 


GAME OVER; 


130 


BET 5 CREDITS; 


131 


PUSH SPIN; 


132 


INSERT BILL; 


133 } 
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135 # Critical Event Function Pointers # 

136 # # 

137 # Below is a reference list of the currently supported # 

138 # functions calls in the engine keyhandler. . . # 

139 # # 

140 # THIS SECTION SHOULD NOT BE CHANGED! # 
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142 keyhandler : { 

143 fnain_ciosed; 
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144 


mai n_open; 


145 


cash_cl osed; 


146 


cash_open; 


147 


1 ogi c_cl osed; 


148 


logic_open; 


149 


hopper_cl osed; 


150 


hopper_open; 


151 


printer_closed; 


152 


pri nter_open; 


153 


drop_cl osed; 


154 


drop^open; 


155 


bi 1 l_clear; 


156 


bi 1 1 _error; 


157 


pri nter^error; 


158 


pri nter_cl ear; 


159 


billup_swftch; 


160 


bi 1 1 dn_swi tch; 


161 


coi nup_swi tch; 


162 


coindn_swi tch; 


163 


coi nrev_swi tch; 


164 


hopperup_swi tch; 


165 


hopperdn_swi tch; 


166 


hopperful 1 up_swi tch; 


167 


hopperful I dn_swi tch; 


168 


bi 1 1 1„swi tch; 


169 


bi 1 1 2_swi tch; 


170 


bi 1 1 5_swi tch; 


171 


bill10_swi tch; 


172 


bill20_swi tch; 


173 


bi 1 1 50_swi tch; 


174 


biinoo^switch; 


175 } 




176 meters : { 


177 


<4,3>; # Total In 


178 


<4.6>; # Total Out 


179 


<4,0>; # Drop 


180 


<4, 5>; # Credits Paii 


181 


<4, 4>; # Jackpot 


182 


<4, 1>; # Progressive 


183 } 




184 




185 





2. .OTI Syntax for the Core System 

The following are the syntax rules for . oti . 

1 syntax : group { 

2 # the resource manager expects the following definitions 

3 serial : array of i=port, s=what / port >= 1 and port <= 4, 

4 what = watchdog 

5 or what = touchscreen 

6 or what = bi H acceptor 
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7 or what = protocol ; 

8 kernel : array of S; 

9 output : array of <l =port, i =bi t>, s=what / 

10 port >= 0 and port <= 7, 

11 bit >= 0 and bit <= 7, 

12 what = lockout or what = hoppermtrl or what = hoppermtrh 

13 or what = muteswltch or what = divertera or what = diverterb; 

14 portmap : array of <s=porttype, import, i=bit>, S=letter, S=f unction / 

15 porttype = p or porttype = r or porttype = s, 

16 port >= 0 and port <= 7, 

17 bit >= 0 and bit <= 7, 

18 len(letter) = 1; 

19 panel : array of <s=porttype, i =port, i =bit>, S=letter, s=cb, s=cb2 / 

20 porttype = p or porttype = r or porttype = s, 

21 port >= 0 and port <= 4, 

22 bit >= 0 and bit <= 7, 

23 len(letter) = 1; 

24 lights : array of <i =port, i=bi t>, s / port >= 0 and port <= 7, 

25 bit >= 0 and bit <=7; 

26 meters : array of <i=port, i=bit> / port >= 0 and port <= 7, 

27 bit >= 0 and bit <= 7; 

28 keyhandl er : array of S; 
29 

30 # the other parts of the system use the following 

31 runtime : group { 

32 load : S; 

33 ? prel oad : array of S; 

34 } 

35 startup : array of s=what / 

36 what = display 

37 or what = sound 

38 or what = touchscreen 

39 or what = chimp 

40 or what = bi 1 1 acceptor 

41 or what = protocol ; 

42 debug : group { 

43 output : s=what / what = fi I e or what = consol e or what = seri al ; 

44 options : array of s; 

45 } 

46 # does anyone use this? 

47 nvram : group { 

48 medi a : s=what / what = f II e or what = sram or what = dram; 

49 } 

50 # these things are used by the engine 

51 coordinates : group { 

52 % : i =x J =y, i =w, i =h / x+w <= 800, y+h <= 600; 

53 } 

54 infostrings : array of S; 

55 # define a default item 

56 % : free group ; # a group type with no syntax group, but which can define 

57 # its own syntax group inside itself. 

58 } 
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3, New .OTi File Syntax 

The first part deals with the syntax of the . oti file itself The second part covers how to 
retrieve data from the , otI file in C. 

A- Very Abstract, Broad Overview 

The . oti file provides a way to structure configuration data. The data is then easy to 
retrieve at run time using simple function calls. The file can also specify syntax, allowing 
dynamic type checking of data in the file, 

B. Basic Structure Elements 

Three structure elements are provided: "groups,'* "arrays," and **rows." "Rows" hold the 
actual data, consisting of integers, strings and real numbers (internal: real numbers even 
needed? Are other basic data types needed instead?). Arrays and groups just provide orga- 
nization for the rows. An array is simply a homogeneous list of items, (rows, groups, or 
other arrays). Groups allow for a heterogenous collection of items, each one bound to a 
name. 

0. Basic Typing 

For each of these basic elements, a "subtype" of that element can be defined. After the 
resource manager loads a file, the groups, arrays, and rows, it then checks to see if each 
structure element matches its subtype. 

The subtypes are defined either in file or in an auxiliary file, (internal: in fact, the specifics 
of this need to be worked out.) Rows can define how many data items they have and each 
of their types, i.e. string, integer, real. Rows can also specify formatting characters <>(), 
and restrictions on the values of the data in the row. Arrays types specify the subtype of 
their elements and restrictions on their size. Groups can give a list of names to be in the 
group and their subtype. 

D. File Syntax 

A row is a list of items separated by commas. The items are either numbers, strings or for- 
matting characters. A row is ended with a semicolon. An example row: 

5, seafood platter; 

An array is enclosed in braces {}. The items in an array are not separated if they are rows, 
since the semicolon on the end of every row separates them well enough. Otherwise, the 
items are separated with commas, just for aesthetic reasons. An array of rows: 



{ 5, seafood platter; 
458, 1 1 ght bul bs; 

} 



An array of arrays: 
{ 

{ 1; 2; 3; }, 
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{ 4; 5; 6; }, 

{ 123; 456; 789; } 



} 



Groups are also enclosed in braces {}. Groups are distinguished from arrays by the pres- 
ence of bindings. A bindings is represented by a colon and it serves to unify a name with a 
value. A binding looks like: 

<nanie> : <item> 

The item is either a row, an array or another group. An example group: 
{ 

name : papa smurf; 
age : 150; 
parents : { 

mother : Betty; 

father : Barney; 
} ^ 

} 

The file itself is treated as one group so that everything in a file is bound to a name. 
E. Defining Subtypes 

A row subtype is given as a list of format specifiers. The format specifiers are 
i <- integer 
s. <- string 

S <- case sensitive string 
f <- real numbers 

First a few notes. All strings specified as s are converted to lowercase. The f format char- 
acter really stores its data as the C datatype doubl e (and not as f I oat). 

These format specifiers are separated by commas. In addition, formating angle brackets 
and parenthesis can also be given, in pairs. An example row type: 

S, (i,i), <ij> ; 

The type is ended with a semicolon. In addition, restrictions on the data values can be 
given. The first step is to give each data value of interest a name. This name is local only 
to this row type. Not every element needs a name. The name is assigned by following a 
format specifier with an equals sign and then the name of the variable. An example: 

S, (i=x, i=y), <i,i>; 

Now that we have variables we can use them in expressions. The available operators for 
expressions (from lowest to highest precedence): 
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Bool X Bool -> Bool 

« 1 

and or 

Bool -> Bool 
not 

NUMBER X NUMBER -> Bool 
String x String -> Bool 
= 1= < <= > >= 

NUMBER X NUMBER -> NUMBER 

+ 

* / 

String -> Integer 
lenO 

The comma operator (under Bool x Bool -> Bool ) is simply a very low-precedence and 
operaton This allows the writing of expressions such as 

x>0, y>0 

which allows one's eye to group the terms better. NUMBER is either Integer or Real, len' 
gives the length of a string. Parenthesis can be used to group sub-expressions. A restriction 
expression should evaluate to the boolean 'TRUE' if the data is okay. Any other value gen- 
erates an error. Thus, the expression 



would cause an error since it is the integer 1. The expression 
1 = 1 

evaluates to Boolean TRUE, and doesn't cause an error. The restriction expression is offset 
from the row definition by a forward slash. An example: 

S, (i=x, i=y), <i=w, i=h> / x>0. y>0, w>0, h>0, 
x+w <= 800, y+h <= 600; 

Two examples of valid rows based on this subtype: 
What, (200,200), <100, 100>; 
Are, (300, 500), <"100", 100>; 

The second row is valid, even though the first 100 is in quotes because of how files are 
read in. Initially everything is read in as a string. When the subtype is appUed to this row it 
tries to convert the strings which should be integers to integers. If it can't, an error is 
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raised Now, three examples of an invalid rows based on this type: 
You, (45, 67, 56); 
Doing, 1,1,1,1; 

"Here?", (500, 500), <200,200>; 

The first row is invalid because it doesn't have enough elements. The second row doesn't 
have the right formatting. The third row has the correct format, but the data doesn't fit the 
restriction, since 500 + 200 > 600, 

Array subtypes begin with the keyword array of followed by another subtype definition 
which gives the type of the elements in the array. An example: 

array of i, s; 

This gives an array of rows, each row consisting of an integer and a string. Any type defi- 
nition is permitted, even 

array of array of array of i , i ; 

Which defines an array of arrays of arrays of pairs of integers. To make it easier to see the 
grouping of arrays, braces can be used: 

array of { array of { array of {i,i}}}; 

Notice that the semicolon moved to the outside of the braces. Arrays can also have restric- 
tions. The restrictions are defined the same as they are for rows, except that arrays only 
have one variable: I ength. This is an integer giving the number of elements in the array. In 
addition, if an array has a restriction attached to it, the braces must be used This prevents 
the restriction for the array fi-om being confiised with the restrictions for the row or other 
arrays. An example: 

array of { array of i,i } / length > 5, length <= 10; 

Group subtypes are identified with the keyword group. This is followed by an opening 
brace. Inside the brace is a list of bindings. These bindings associate a name with a type. 
An example: 

group { 
city : s; 



Associates the row subtype of a single string to the name ci ty. The data would look like: 
{ 

city : New York; 

} 

The element bound to ci ty in the data has the type bound to ci ty in the definition. In addi- 
tion, the name ci ty is a mandatory binding and something must be bound to it in the data. 
An invalid group to the previous subtype is: 



} 



{ 
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town : New York; 

} 

Because there is no binding to ci ty. Also invalid: 
{ 

ci ty : New York; 
state : New York; 

} 

Because the subtype was not expecting a binding to state. This limitation motivates hav- 
ing optional bindings and default bindings. An optional binding may or may not appear in 
the data, a default binding is used for every name which the group subtype does not know 
how to deal with. An optional binding is indicated by putting a question mark before the 
binding name. Example: 

group { 

? city : s; 

} 

A default binding is indicated by binding to %. (internal: perhaps another keyword, e.g. 
"default"?). Example: 

group { 

% : s; 

} 

Since the group type uses different name spaces for its mandatory bindings table and its 
optional bindings table it is possible to define 

group { 
city : s; 
? city : i; 

} 

In all cases, the group type first searches its mandatory binding table and then its optional 
binding table, and then finally it uses the default type, if there is a default type. 

There is one more special kind of binding. A group type object allows you to define a type 
once and then use this type over and over. These are called "pure" types since no data can 
ever bind directly to them. Pure types are indicated by the keyword type before their 
name. Example: 

group { 

' type guess : f=low, i=high, i=guess / low <= guess, guess <= high; 

} 

No data objects can have this subtype of a group since it doesnH define any data bindings, 
it only has one pure binding. The definition can use this pure binding anywhere a subtype 
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is needed. Example: 
group { 

type guess : i=iow, Uhigh, i=guess / low <= guess, guess <= high; 

a : ^ guess; ^ 
b : array of ^ guess; 
c : group { 
c : 'guess; 

} 



The back-quote makes a reference to the pure type. Then, when this reference is needed, 
the pure type is found and used. The references are not resolved at load time, only when 
they are needed. This means that the following passes without error since the optional 
binding to dog is not evaluated because there is no binding to dog: 

subtype: 
group { 



cat : whiskers; 

} 

subtype definitions are identified by being bound to the name syntax. This means that the 
definitions must be the member of some group (any group may have a syntax binding, in 
fact). When a binding to syntax exists it is either deleted or it is used as the local syntax 
rules for parsing the group it is found in. The choice is up to the original subtype for the 
group with the syntax bindings. By default a group may not define its own syntax. To 
allow a group this fi*eedom, the keyword free is placed before group in the subtype defini- 
tion. The group definition for a free group is just the default subtype to use, in case the 
group does not have a syntax binding. An example: 

subtype: 

free group { 
greeting : S; 



? dog : ^dog_name; 
cat : s; 



} 



data: 



{ 



} 



data: 



{ 



syntax : group { 
% : i, i; 
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} 



b : 



a 



1, 2; 
3, 4; 



} 



This is valid. The group subtype is declared free. The data has a binding to syntax giving 
alternate rules for this group. These rules are used to check the data. 

An interesting point is that pure types are scoped and are available to all the subtypes in 
the group. The scoping should take into account the lazy evaluation of the references. 

subtype: 
group { 



type state : S; 
% : free group { 

dest : ^clty; 

} 

} 

data: 
{ 

first : { 
dest : { 

name : New York; 
where : New York; 

} 

} 

second : { 

syntax : group { 

type * state : S, l=zlp; 
dest : ^city; 



type city : group { 
name : S; 
where : ^ state; 

} 



} 

dest : { 



name : Denver; 



where : Colorado, 80950; 

} 



} 



} 
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TJiis is a contrived example, but it shows many things with type references. First, they are 
scoped. In the subtype definition of city, the reference to state is resolved in the parent. 
In die data, the group bound to second redefines the type state and uses a reference to 
city. The reference to city uses a reference to state, however the state type which is 
used is not the new redefined state, the type used for state is the one defined in the scope 
of the original definition of ci ty. This behavior is similar to closures in Scheme, 

Since subtype rules are identified by a binding to the name syntax, the element bound to 
syntax is a group subtype. 

F. .otiFiie 

The . oti file is treated as one large group. Thus, every element in the . oti file is bound to 
a name, and an .oti file may specify a syntax group to give new rules for it (but only if it 
is allowed). 

Comments are started with a pound sign (#), and continue to the end of the line. To use the 
pound sign in a string, enclose the string in quotes. 

G. Lexai Issues 

All elements are read in from the file as a string. Only during the second step, rule check- 
ing, are the strings converted to integers or real numbers. This allows one to have strings 
of digits, and it also allows a number to be represented in many ways. Numbers can be 
written in decimal, hex (with a Ox prefix), and octal (with a leading zero). Real numbers 
can be written in scientific notation (e.g. -4. 63e-28). Strings can be written in quotes, 
either single or double. Quotes inside can be escaped with a back-slash. Examples: 

"He said, 'Hello* " 
'He said, "Hello"' 
"He said, \"Hel!o\"" 

If you want something with the same name as a keyword, put it in quotes. Items in quotes 
are always identified as strings. In the following example the word "syntax" in quotes is 
not identified as the keyword syntax. 

"syntax" : Something not giving rules; 

H. Arcane Torture and File Grammar 

The fiiU grammar of the oti file is simple and boring. Here is the grammar of the restriction 
expressions, mildly more exciting. Notice that there is no provision for numbers. Strings 
are automatically coerced into integers and reals as needed. This allows both the string 
equality 

s=string / string = "1"; 

and the integer equality 
l=fnteger / integer = 1; 

to be written as 
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s=stnng / string = 1; 
j -integer / integer = "1"; 

although the second fonn is not very useful, and even a little misleading. The grammar of 
restrictions in the subtype definition: 

restri cti onl i st : = restri cti onl i st * , * restri cti on 
I restriction 

restriction := restriction AND r_tenn 
I restriction OR r_term 
I r^term 



r term 



:= idop 
I NOT idop 



idop 



:= idterm idterm 

I i dterm * ! =' i dterm 

I i dterm ' <' i dterm 

I i dterm ' <=' i dterm 

I idterm idterm 

I idterm idterm 



i dterm 



;= idterm '+* idfactor 
I idterm * idfactor 
I idfactor 



idfactor Idfactor ' *' idexp 

I idfactor V* idexp 
I idexp 



idexp 



:= STRING 
I LEN ' C STRING 
I • (' restriction * )* 



4- .OTi File Addresses 

The data in an . oti file is organized hierarchically. This allows us to define an address string 
to retrieve data. Elements in a group are identified by the name that they are bound to. Ele- 
ments in an array are indexed by a 0 based non-negative integer in brackets. The addressing is 
very similar to the addressing of C structures and arrays. Consider the data: 

boxes : { 



Rev: May 2001 



/^Shuffle Master 



186 



wo 03/023647 



PCT/US02/30286 



D.4- .oti File Addresses 



D-15 



1,1,50,50; 
100,100, 50,50; 

} 

arrayofgroups : { 
{ 

name : Papa Smurf; 
age : 150; 



} 

} 

Job : { 

type : busboy; 
wage : 8.00; 

} 

row : 1,2,3,4, "time to go"; 
The last line has the address 



The boxes are addressed as 
boxes [0] 
boxes [1] 

In addition, arrays define an unplicit element i ength which returns a single integer telling the 
number of elements in the array. This element would be addressed as 

boxes. length 

And we would get back 2. The groups are addressed as 
arrayofgroups [0] 
arrayofgroups [1] 

The elements in the array of groups are addressed as 
arrayofgroups [0] . name 
arrayofgroups [0] . age 

The items in job are addressed as 
Job. type 
J ob. wage 

Ultimately what is returned is a list of data — the list of data in the row. 



name : Furby; 
age : 1; 



row 
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Appendix E — mygame.state File 



game.state file listing: 
# 

# GameState structure definition 
# 

U REQUIRED BY COMMON GAME ENGINE LAYER *♦**♦♦* 

# Common game configuration elements used by the engine - 

# visible from the game layer... (Additional game specific 

# elements should be created in a game specific configuration 

# structure.) 



char maxbet; 

char denomination; 

char bitmapped; 

char touchscreen; 

char credit_display; 

char bonus; 

char progressive; 

char network; 

int betinc; 

int red; 

int green; 

int blue; 

int cash_Umit; 

int credit_limit; 

int handpay_limit; 

int cashout_nmit; 

int volume; 

int payoutpercentage; 

int pay table; 

int hopper^fili; 

} Config; 

# Local Game NVram 
# 

# All game specific components should reside here... 
struct ball 

{ 

int x; 

int y; 

int x_vel; 

int y_vel; 

int start_x_vel; 
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int start_y_vei; 
int startjc; 
int start_y; 
char rectangle; 
int count; 
int current^rect; 
} BBall; 
struct bonus 

{ 

int bonustrigger; 
} Bonus; 
struct template 
{ 

int workingcxample; 
} Template; 
struct history 

{ 

int example; 
} GameHistoryI70]; 
struct winners 



long rect_0; 

long rect_l ; 

iong rect_2; 

long rect_3; 

long rect_4; 

long rect_5; 

long rect_6; 

long rect_7; 

iong rect_8; 

long rect_9; 

long rect_IO; 
long rect_ll; 
long rect_12; 
long rect_l3; 
long rect_14; 



{ 



} Wmner[4]; 
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Appendix F — Generic Game Template File 



1. Generic template.c File Listing 



^include <userap!.h> 
#include "game.h" 

// include local game & graphics headers 
^include "genertc_template,h*' 



^« 4|t « * 4e * « * 4( * 4( * « 4t 4t « « «/ 

/♦ Engine Hooks */ 
void init_gaine(void) 

{ 

// Local data initialization 
} 

void reset_game(void) 
{ 

int volume; 
// Initialize all local game nvram 

nv_setchar("Config.denomination",(char)100/DENOMINATION); 
nv_setchar("Config.maxbet",(char)MAXBET); 
nv_setintC'Config.betinc",(int)BETINC); 
nv_setchar("Config.bonus".(char)DOBONUS); 
nv_setint("Config.payoutpercentage",920 1 ); 

nv_getint("Config.voIume",&volume); 
sound_volume( volume); 



void begin_play(void) 

{ 

// Local housekeeping and display cleanup 
nv_setint("TempIate.working_exampIe",0); 
} 

void play_one(void) 
{ 



} 
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// First stage game animation and logic 

SetCurrentGameState((char)PLAY2); 

} 

void play_two(void) 
{ 

//Second stage game animation and logic 

SetCuiTentGameState((char)EVALUATE); 

} 

long evaluate_game(void) 
{ 

// Compute payline award amount and return value 

return 0; 

} 

void finish_game(void) 
{ 

// Local housekeeping 
} 

void bonus(void) 

{ 

// Local pre-bonus logic & animation 

mod_load("bonus"); 

} 

void attract(void) 

{ 

SetCurrentGameState((char)IDLE); 
) 

char check_forjackpot(void) 
{ 

char j ackpotlevel ; 
jackpotlevel=0; 
return jackpotlevel; 
} 

char check_for_bonus(void) 
( 

char bonusflag; 
bonus flag=0; 
return bonusflag; 
} 



long bonus_complete(void) 

{ 

return OL; 

} 
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void animate_winner(void) 
{ 

// Winner animations (ie - paylines...) 

void animate_idle(void) 
{ 

// Idle mode animations 
) 

void maxbet_game(void) 
{ 

// Local maxbet logic and display routines... 
} 

void cache jgfx(void) 
{ 

// Load grapiiics into cache 
} 

void pick_numbers(void) 

{ 

int number; 

number=md_get_number(52); 
} 

void draw game screen(void) 

{ 

makebuttonl("PLAY".510,530,60,60,GREEN;'spin_switch"); 
makebuttonirBET" ,400,530.60,60,LTBLUE,"bet_switch"); 
makebutton I ("MAX",7 1 0,5 1 0,60.60,LTGREEN."maxbet_switch"); 
makebutton I ("COLLECT", 1 2,545,60,50,LTRED."coIlect_switch"); 
makebuttonl("HELP",115.545,60,50,YELLOW."heIp_switch"); 

} 

void update_lights(void) 
{ 
} 



2- GENERIC TEMPLATE.H FILE LISTING 
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Appendix G ~ Graphics Conversion Tool 



1 . Location and Use of convgfx-py File 

You will find the convgfx.py graphics conversion tool on the SGOS CD-ROM, ***Specify 
directory when known*** 

Refer to Chapter 14 for an overview of how to store and organize your graphic icons and use 
the convgfx. py tool to covert them to XPM format. 

2. File Listing 

File Listing G-I provides a listing of 

File Listing G-1: convgfx.py 

1 Place the final version of convgfx.py here 

2 

3 

4 

5 

This file is included in the SGOS installation CD-ROM. 
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Appendix H — Makestrips Utility (9 Line Games) 



1. The Makestrips Utility 

Makestrips will turn a list of par-sheet files into C source code arrays. Since every par-sheet 
file has a different format, the task is complicated, but is still conceptually very simple: 

• Read in the strip data from the par-sheet files. 

• Format the data into a C header file. 

Makestrips not only has many options governing how its default procedures do both steps, it 
will also let you replace either step with your own code. 

To allow all this customization, Makestrips requires an auxiliary file to hold the settings of the 
various options. This file may have any name, but the default name Makestrips looks for is 
"makestrips.opt". If your file has another name you will need to specify it on the command 
line with the "-o <filename>" or optionfile <filename>" options. If you do not have an 
option file at all, you can either make one with a text editor, or run Makestrips with the "-n" or 
"—new" options. If you do the latter, you will still need to edit the resulting file to fill in impor- 
tant options, such as the par-sheet filenames. 

Makestrips, by default, is lazy and checks the modification times of the option file and the 
input files against the modification time of the output file to see if the reel strips are already 
up-to-date. The check can be overridden by using the "-f ' or "—force" options, or by setting the 
option [check mod times] in the option file to a blank line. 

The header file generated by Makestrips has the format as shown in Figure [refrenc^ to 
Fiheadfile]. The elements in angle brackets o are user specified options. The options in the 
repeated block are represented in the option file as a list of values in the order they are to be 
used. 



/* [output f i I e] 

* file automatically generated by makestri ps. py 

* creation date and time 
V 

#i f ndef [output f i I e] 

#def i ne [output f i I e] 

<head> 

+ + 

|#ifdef [current percentage] 
|#define PAYOUTPERC [current payout] 
I [array name] = { 
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I first reeJ strip, 
I second reel strip, 

I last reel strip 

!>; 

|#endif 

+ + 



<tai I > 
#endi f 



[figure F:headfi le] 

2. USING MAKESTRIPS 

The command line syntax for Makestrips is: 

. /makestri ps. py [-f | —force] [(-o ] — optionfile) <filenanie>] £(-n | --new) 
[<fi lenaine>]] 

3. Customizing Makestrips 

Makestrips has many options which can be set, but options can only be set from an options 
file. Every option has a name which may include spaces and a corresponding value or list of 
values. Some options have defaults and do not need to be given specifically, although they can 
be assigned new values by specifying them. Other options do not have default values and must 
be included in the option file. 

The list of options to be presented are organized according to what conceptual step they apply 
to: reading a par-sheet file, writing the C header file, or general options. An option description 
beginning with a marks options which do not have default values and are required, other- 
wise the default values are given. 

A. General Options 

* [input files] A list of par-sheet files. The order the files are listed is important, since 
the files are processed in the order listed. Their order should correspond with the order of 
the [percentages] and [payouts] options. 

* [output file[ The name of the C header file to be created (with extension), 

* [check mod times] Set to eitiier 0 or 1. 0 forces the reel strip file to always be recom- 
puted. This is the same as the "-f or "—force" command line options. If set to 1, 
Makestrips will only remake the reel strip file if the file modification times indicate that 
the reel strip file is out of date. The default value is I. 



repeated for every [input file] 
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B. Par-sheet Parsing Options 

There are two reel strip parsers biult into Makestrips: the default parser and the extended 
parser. Between the two of them just about any kind of paytable file can be read, but if 
these options are not enough, you can even write your own parser (see section [refirence to 
S:reelparser]). 

The simple parser should be enough for most situations. It expects a tab delimited file and 
reads in the reel strips, one per column. The option [start column] adjusts the column the 
reel strips begin at. The extended parser, by contrast, uses regular expressions to interpret 
each line, and has the ability to go through a list of expressions until it finds one that 
matches^ 

Conunon Parser Options. The two parsers share a few options. These options have the 
same meaning with both parsers. 

* [start line] A regular expression describing a line before the reel strips. The lines of 
each input file are read and discarded until a line matching [start line] is found. Reel 
strip parsing begins with the next line. If nothing is given, the parsing begins with the 
first line of the file, 

* [stop line] A regular expression describing the line to stop on. Once parsing has 
begun, every line is checked against [stop line]. When a line matches the Une is dis- 
carded and reel strip parsing of the file stops. If nothmg is given, the parsing goes 
through every line of the file. 

* [num reels] The total number of reels. The default value is 5. 

* [extended parser] If set to 1, the extended parser will be used. The default value is 0- 
— use the simple parser. 

Simple Parser. The simple parser assigns each reel to a column of the input file. It is 
important to specify [start line] and [stop Une] so that the parser won't put whatever extra- 
neous garbage that is also in that column into the reel strip. 

* [start column] An integer giving the column the first reel strip is in. The other strips 
are assumed to be in the next [num reels] columns. This option is zero based, making 
the first column 'column 0'. The default value is 0, 

Extended Parser.The extended parser uses regular expressions. It starts with the pattern 
given in [line pattern 1]. If the current line matches the pattern, the reel values are pulled 
fi-om the line by grouping marks in the pattern. The groups are mapped into the reel strip 
arrays by the option [line map], with the first group going to the first reel strip index in 
[line map], the second group to the second index in [line map], etc. The pattern matching 
continues until a line doesn't match the current line pattern. If the option [line pattern 2] is 
given, [line pattern 2] become the new pattern and the current line is re-parsed with it, oth- 
erwise the current line is skipped, the pattern is not changed and the next line is read. 
Repeat this process for each line pattern in the option file. Whenever a new line pattern is 
loaded, the next [line map <n>] is searched for. If no line mapping is given, the previous 
one is used. 

* [line pattern <n>] A list of regular expression patterns. There should be grouping 
elements \y in the expression, one for each value to be extracted. The extracted val- 
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ues are put in left to right order into the strips for each reel. If there are more groups 
than reels, an error occurs. If [line pattern] is a list of expressions, the expressions are 
joined together with the regular expression which will match anything that is not 
alphanumeric or ^ J such as spaces, tabs and commas. Only required if [extended 

parser] is set to "'1". 

* [reel map <n>] A list mapping the grouping elements in [line pattern <n>] to reel 
strips. Only required if [extended parser] is set to 1". 

C. C Header File Options 

* [head] A list of text to insert at the beginning of the header file. Since Makestrips already 
inserts its own header, [head] would follow. 

* [tail] A list of text to be included at the end of the header file, [tail] appears before 
Makestrips's tail. 

* [percentages] The list of percentages, "payouts" - the list of percentages and payouts. 

4- The Format of the options file 

The most important item in an option file is a tag, which names a specific option. A tag begins 
with a left bracket, '[*, in the first column, and ends with the first right bracket ']' on the line. 
All the text between the brackets is the option tag; all text remaining on the line is ignored. 
After a tag line, the lines after the tag are read in, even blank lines, and stored associated with 
the option given by the tag. An exception is the blank lines between the end of a tag's items 
and the next tag: these blank lines are ignored. However, the blank lines occurring between a 
tag's items are stored. The text before the first tag in the file is also ignored, allowing a nice lit- 
tle area for comments. The only other space for comments in the file are on a tag line after the 
tag. 

A special exception is given to the text following the the tags [start line], [line pattern], and 
[stop line]. These tags require regular expressions, and need to use the left bracket, "*[*, charac- 
ter. A single space placed at the start of a line will be striped out, allowing regular expressions 
to begin with a left bracket "['. If your regular expression needs to begin with a blank space, 
start the line with two blank spaces since only the first one is removed. 

The order the options are given in the file are unimportant. 

5- Writing a Par-sheet Parser 

In case the two parsers built into Makestrips are not adaptable to read your par-sheet file, it is 
possible to write your own file parser. The parser should be a code snippet (not a fimction def- 
inition), and be included in the option file under the option [user parser]. The code snippet is 
expected to read in the option file and make assignments to the variable "reels", which is a list 
containing as many lists as reels. (As given by the option [num reels].) The first reel has index 
0, the second reel index 1, etc. This variable will then be written to [output file] by Makestrips. 
Your code snippet can use the following implicit variables: "reels", "filein", "stopjpat", and 
"get_option()", as well as using any builtin variables and importing as many modules as it 
likes. No restrictions are placed on the execution environment. The variable "reels" is the vari- 
able you should assign strings to, this is the variable printed into the header file, "filein" is an 
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already open file object. The file position pointer has already been advanced to the first line 
after the line described by [start line]. "stop_pat" is a regular expression describing the line to 
end on. Your code does not need to make use of it. "get_option("<option name>")" is a func- 
tion which will return the value of the option <option name>, which is passed as a string. The 
option will be returned as a list of strings, with each string being a separate line in the option 
file. Although your parser will be invoked once for every par sheet file, there are no provisions 
for the script to pass variables between invocations. 

As an example, here is the simple default parser as it would look in the option file if it were 
written as a code snippet. 

[user parser] 
import re 
import string 

start_coI = 1 nt(get_opti on (' start column')[0]) 
num_reels = int(get_optionC num reels')[0]) 
end_coI = start__col + num^reels 
for I in fl lain. readlinesQ: 

if stop_pat and re.match(stop_pat, I): 
break 

tok = stri ng. spl i t(l [: -1] / ' ) 
i = 0 

for sym in tok[start_col :end_col ]: 
i f sym ! = " : 

reel s[i ] . append(sym) 
i = i + 1 
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Appendix I ~ Nine Line Game Template 



1. NiNELiNEjTEMPLATE.c File Listing 

add when available 

2. NINELINE.TEMPLATE.H FILE LISTING 

add when available 
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Appendix J — Poker Game Template 



1. POKER_TEMPLATE.C FILE LISTING 

add file lising when available ^ this is font 
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Appendix K — Other Templates 



these templates are under construction 

1. Help Template 

2. Last Game Template 

3. Pay Table Template 

4. Bonus Template 
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Appendix L — Online Protocol Exception Codes 



Exceptions.h is a complete list of olga (Shuffle Master's Online Gaining Architecture) excep- 
tion codes. With the relevant exception codes below olga will handle exceptions for sas, sds, 
and ogp protocols. 



exceptions.h listing: 
/♦ 

Shuffle Master Game Library 

Copyright (c) 1999-2000 Shuffle Master, Inc. 

All Rights Reserved. 

$Revision: 1.5 $ 

$Author: mdj $ 

$Date: 2000/07/31 22:00:23 $ 



#ifndef ^EXCEPT! ONS_H 
#define _EXCEPTI ONS_H 

// these def i nes are for al I possi bl e except! ons 

// door events 

#define MAI NDOOROPENEDOxOI 

#define MAI ND00RCL0SE00x02 

#def i ne DROPDOOROPENEDOxOS 

#deflne DROPDO0RCLOSE0Ox04 

#define LOG! CDOOROPENEDOxOS 

#define LOGI CDOORCLGSEOQxOS 

#define CASHD00ROPENEDOxO7 

#deflne CASHDOORCLOSEOOxOS 

#def i ne BELLYD0OROPENEDOxO9 

#define BELLYDOORCLOSEDOxOA 

#def i ne NOTEDOOROPENEDOxOB 

#define NOTEOOORCLOSEDOxOC 

#define D00R70PENED0x0D 

#deflne D0OR7CLOSED0x0E 

^define DOORSOPENEDOxOF 

#defl ne DOORSCLOSEDOxlO 

// hopper & coin events 

#define H0PPERFULL0x12 
#define H0PPERL0W0x13 
#def i ne H0PPEREMPTY0x14 
#define OVERRUNOxIS 
#define 001 N0UTERR0R0x16 
#define COlNINERROROxl? 
#define 01 VERTERERROROxIS 
#def i ne REVERSECO I NOxl 9 
#define COINLOCKOUTFAILOxIA 



V 
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#define COINOUTJAMOxlB 
#define COINDROPOxIC 
#define TOKENDROPOxlD 
#define CASHOUTCOI NSOxlE 
#define CASHOUTTOKENSOxlF 
#deffne WfNC01NS0x20 
#define *l NT0KENSOx21 
#def I ne Wl NCREOI TS0x22 
#def t ne CREDI TSFROUCOl N0x23 
#define CREDI TSFROMT0KENOx24 

// reel events 
#define REELTiLT0x27 
#define REEL1TI LT0x28 

#define REEL2TI LTOx29 
#define REEL3TI LT0x2A 
#define REEL4TI LT0x2B 
#define REEL5TI LT0x2C 
#define REEL6TI LT0x2D 
#def i ne REELDl SC0NNECT0x2E 
#def i ne REELST0PPED0x2F 

// bill and stacker events 

#define ACCEPTORFA! LR0M0x32 
#def i ne ACCEPTORFAI LCS0x33 
#define ACCEPTORFAI L0x34 
#define ACCEPT0RJAM0x35 
#define STACKERJAM0x36 
#define REVERSEBI LLOx37 
#define Bl LlREJECTED0x38 
#defjne 81 LLC0UNTERFEIT0x39 
#define STACKERFULLOxBA 
#def i ne CASHBOXREMOVEDOxSB 
#def i ne CASHBOXI NSTALLEDOxSC 
#define BlLLim0x3D 
#define BILUN20x3E 
^define BILLIN50x3F 
#define BILLINI 00x40 
#define BILLiN200x41 
#define BiLLlN500x42 
#define Bl LLIN1000x43 
#define Bl LLI N2000x44 
#define Bl LLlN5000x45 
#define Bl LLIN1CHANGE0x46 
#define Bl LLIN2CHANGE0x47 
#define BILLiN5CHANGE0x48 
^define BiLLIN10CHANGE0x4g 
#define Bl LLI N20CHANGE0x4A 
#defjne BlLLIN50CHANGE0x4B 
#define BILLIN100CHANGE0x4C 
#define BILLIN200CHANGE0x40 
#def i ne Bl LLI N500CHANGEOx4E 
#define BlLLIN$480x4F 
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// printer events 
#deftne PRI NTER0FF0x52 
#define PRI NTER0N0x53 
#define NEEORi BB0NOx54 
#define CARRtAGEJAM0x55 
#define PRI NTERC0JIIM0x56 
#define PAPERL0W0x57 
#define PAPER0UT0x58 

// user generated events 
#deftne WAl Tl NGFORUSEROxSB 
#define CANCELHANDPAYOxSC 
#define CASHOUTBUTTONOxSD 
#define BUFFERFULLOxSE 
#define CHANGEREQUESTEOOxSF 
#deftne GAMEST0P0x60 
#define DRAWCARDS0x61 
#define BET0x62 
#define CAR0HEL00x63 
#define 6AHESELECTE00x64 
#define GAMESTART0x65 
#define GAMESTARTC0IN0x66 
#define GAMESTARTCREDi T0x67 
#define GAMESTARTT0KEN0x68 

// attendant generated events 

#def i ne CHANGECANCELED0x6B 
#define BILLTOTALSRESETOxGC 
#define OPTIONCHANGEOxGD 
#define JACKPOTRESETOxGE 
#define OlSPUYMETERSOxBF 
#def t ne 01 SPLAYMETERSEXI T0x70 
#define SELFTESTSTARTOxTI 
#define SELFTESTEND0x72 
#def i ne RECALL0x73 
#def i ne S0FTMETERSRESET0x74 

// memory events 

#define RAMREC0VERED0x77 
#define RAMCLEARED0x78 
#def I ne RAMBAD0x79 
#denne R0UERR0R0x7A 
#define R0MBAD0x7B 
#define R0MCHECKSUMCHANGE0x7C 
#def i ne R0MCHECKSUMERR0R0x7D 
#define PR0MCHECKSUMCHANGE0x7E 
#define PR0MCHECKSUMERR0ROx7F 
#define MEMORYRESETOxBO 
#deflne BATTERYLOWOxBI 

// progressive 

#defi ne PROGRESSI VELI NKFAI L0x84 
#define PROGRESSI VEJACKP0T1 0x85 
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#define PROGRESS I VE J ACKPOT20x86 
#define PROGRESS I VEJACKP0T30x87 
#define PROGRESS I VE J ACKP0T40x88 
#define PROGRESS I VEJACKP0T50x89 
#define PROGRESS I VEJACKP0T60x8A 
#define PROGRESS I VEJACKP0T70x8B 
#define PROGRESS I VE J ACKPOT80x8C 
#define SASPROGRESStVEOxOD 

// other events 
#define P0WERUPOx90 
#define POWERDOWNOxOI 
#defiiie GENERALTI LT0x92 
#define CASHOUTTI CKET0x93 
#defme HANDPAYJACKP0T0x94 
#define HANDPAYCREDITS0x95 
#define CASH0UTOx96 
#define RESETDURI NGPAY0UT0x97 
#defme BONUSPAYOxOS 
#define OUTOFSERVI CE0x99 
#define T0UCHERROROx9A 
#define SI GNERR0R0x9B 
#define PR0CESSQRRESETOX9C 

#endff 
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Appendix M - Screens for Setup and 
Recordkeeping 



1. Main Screen 

SGOS provides default screens for several setup, recordkeeping and diagnostics features. The 
following screen offers eight further options: 

• Machine Statistics 

• Ticket-Bill History 

• Last Games 

• Location Information 

• Exit 

• Test 

• Configuration Guide 

• Out of Service 



Figure M-1- 
Setup, 
Recordkeep 
ing and 
Diagnos*- 
tics Main 
Screen 



P3LESS 'SnRVTCE* TO MOVE CUTTOX 
PRESS "COLLECT TO SELECT 



2. Machine STATISTICS 

The "Machine Statistics" button on the main screen leads to the two screens shown in Figure 7 
and Figure 8. The items tracked in Figure 7 are as follows: 



"Soft Meter" ItemExplanation 
Coins InNumber of credits from coins 
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Bills In Number of credits from bills 

Drop Number of credits in the drop (coins only) 

Total In Simple count of total credits in 

Total Outs imple count of total credits out 

Credits PlayedTotal of all credits played 

Credits Won Total credits won by playing, excluding jackpots 

and hand pay 

Credits Paid Credits paid from hopper, excluding hand pays 

or jackpots 

Games PlayedSimple count of games played 

Games WonSimple count of games won 

Hand PayTotal hand pays in credits, including errors paid 

by attendant 

Jackpot Total jackpots in credits, all attendant paid 

Hit frequency% of played games that win 
Awarded %Payback percentage 

3. Error Counts 

The error counts in the following screen are all simple counters as noted. (Each door opening 
counts as an error.) Games played are also simple counts since the last power up or door closed 
events. Coimters max out at 1000 and remain there imtil the next reset/clearing event occurs. 



Figure M-2- 
Machine 
Statistics 
Screen #1 
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Pressing the "Next" button above leads to the following screen which shows the number of 
wins for each possible payline. 
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M-3 



Figure IW-S- 
Machine 
Statistics 
Screen #2 
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4- Ticket-Bill History 

The "Ticket-Bill" button on the main screen leads to the following two screens. The Bill His- 
tory Screen gives the date and time of the last twenty bills accepted, for machines with bill 
acceptors, and a history of tickets printed where applicable. 



Figure M-4- 
Ticket Bill 
History 
Screen #1 
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The Stacker/Hopper Inventory Screen gives a count of bills and coins in the machine (as appli- 
cable). The screen items are as follows: 

Screen Item Explanation 

Stacker Hopper Inventory Accumulates amounts in increments shown 
Stacker Value Gives total value of bills, amount as credits, and actual nimiber of 

bills instacker 

Hopper Value Shows credits in hopper (actual coins); fill amount must match 

bag amount 

ButtonsAttendant can adjust the fill amount with the "increase/decrease" buttons. 
Standard fill amount is set in the Configuration Screen (Figure 18). 
Attendant selects current fill amount with the "add/remove" buttons. 



Figure M-5- 

Stacker/ 

Hopper 

Inventory 

(Ticket Bill 

History 

Screen #2) 



STACKER/HOPPER IMXTiKTORY 
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SETUP EXITS 



The Game History Screen in Figure 11 provides a 70-step game history for resolving player 
disputes. The example below is from a 9-line game. (How/where code in graphics for devel- 
oper's game?) 



5. Location Information 

The Location Information screen accepts basic user data. 
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M-5 



Figure M-6- 
Game His- 
tory Screen 




Figure M-7- 
Location 
Information 
Screen 

6. Diagnostic Test Screens 
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The Diagnostic Tests screen runs five tests as shown in the following screens: 

1. Lights/Switches 

2. Touchscreen 

3. Bill Validator 

4. Hopper 

5. Sound (set volume) 
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At the start of the Light/Switch Test all switches show '^unknown." To test, the attendant or 



Figure M-8- 
Diagnostic 
Tests Menu 
Screen 



PRESS 'SERVICE' TO MOVE BUTTON 
PRESS 'COLLECT' TO SELECT 



slot tech must press each switch to show "good." Note that the setup switch is unknown 
because it is used to exit this menu. 

The touch screen test displays instructions on the screen. 



Figure M-S- 
Touch- 
screen Test 




The bill test screen verifies the bill acceptor operation. The bill is returned after the bill 
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M.6 - Diagnostic Test Screens 



M-7 



denomination is identified. No soft or hard meters are affected by tlie insertion of bills. 

The Hopper Test confirms with pressing the "Start" button that the hopper dispenses coins cor- 



FigureM-10- 
Bill Test 
Screen 



INSERT BILL TO TEST 



SETUP EXITS 



rectly. Test is for 20 coins; the screen below shows the count in progress. No soft or hard 
meters are affected by the dispensing of coins. 



FigureM-11- 
Hopper Test 
Screen 
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PRESS START TO TEST HOPPER 



i 





SETUP EXITS 
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7. Configuration Guide 



The Configuration screen sets the followmg: 



Configuration Setting 
Progressive 
Network 
Cash in Limit 
Credit Limit 
Hand Pay 
Hopper Fill 
Volume 

Network Address 



Explanation 

Whether jackpots are progressive 
Should be "orf' when applicable 

Sets max credit player can accumulate before they must play 

Automatically pays any amoimt above setting 

Any credits won beyond this setting must be paid during cashout 

Standard hopper bag amount 

Speaker volume 

Ref number for this machine (for network, where relevant) 



FigureM-12-|| 
Game Con- 
figuration 
Screen 



•BET' M3VES ACTIVE BinTOH 
•SPIN' INCREASES NUMBER 
DECRE.'\SE5 NureER 
•PRINT' ^DVES CURSOR 

•SETUP' Ems 
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Appendix N — Advantec Hardware Solution 

Information 

1. CHIMP - PCM-5864 EMBEDDED CONTROLLER 

A. Flow/Block Diagram 

Not available from Shuffle Master, please contact Advantec. 

B. Schematic Diagram 
Attached 

C. Layout Diagram 

Please refer to page 7 (Acrobat page 18) of the PCM-5864/L Users Manual, available 
from Advantec. (PCM5864-L.pdf) 

D. Parts List 

Not available from Shuffle Master, please contact Advantec. 

E. Jumper Settings 

Please refer to pages 9-37 (Acrobat pages 20-48) of the PCM-5864/L Users Manual, avail- 
able from Advantec. (PCM5864-L,pdf) 



Jumper 


Name 


Settings 


Selection 


JPI 


ATX power switch 


All pins open 


Not used 


JP2 


Watchdog Action 


Short 1-2, Open 3 


System Reset 


J3 


CPU voltage 


Open 1-2, Short 3-4, Open 5-6, Open 7-8 


2.20V 


J5 


CPU frequency ratio 


Short 1-2, Short 3-4, Short 5-6 


4,5 


J6 


Reserved 


All pins open 




J7. 


CMOS Clear 


Short 1-2, Open 3 


Battery On 


J8 


LCD Backlight 


Short 1-2, Open 3 


Positive 


. J9 


System/PCI clock 


Short 1-2, Open 3-4, Short 5-6 


66MHz/33.3MHz 


JIO 


PCI/Clock 


Open 1, Short 2-3 


33MH2 


Jll 


COM4RI 


Open 1-2, Open 3-4, Short 5-6 


RI 


J12 


COM3 RI 


Open 1-2, Open 3-4, Short 5-6 


RI 


J13 


Compact Flash 


Installed 


Enabled (don't care) 


J14 


COMl RI 


Open i-2. Open 3-4, Short 5-6 


RI 



Rev: May 2001 4C? Shuffle Mastei j 



215 



wo 03/023647 



PCT/US02/30286 



N.1 - CHIMP-PCM-S864EmbeddedControlier N-2 



J15 


COM2 RI 


Open 1-2, Open 3-4, Short 5-6 


RI 


J16 


LCD Power 


Short 1-2, Opens 


+5V 


J17 


Reserved 


All pins open 




J18 


Buzzer 


Installed 


Enabled 


J19 


COM2 Mode 


Short 1-2, Open 3-4, Open 5-6 


RS-232 


J20 


COM2 Mode 


Short 1-3, Short 2-4, Open 5-6 


RS-232 


J21 


COM2 Mode 


Short 1-3, Short 2-4, Open 5-6 


RS-232 


J22 


LCD Shift Clock 


Short 1-2, Open 3 


SHFCLK 


J23 


Audio Power 


Open 1, Short 2-3 


-hl2V 


J25 


TV-Out 


Open 1, Short 2-3 


NTSC 



R Removable Components 

BTl - Battery for CMOS configuration settings. 
U18- BIOS ROM 

U529 - CPU 

DIMl — Dynamic RAM memory module. 



G. 


Connections 




Label 


Function 


Status 


CNl 


CPU Fan 


Not Installed 


CN2 


Motherboard Fan 


Not Installed 


CN3 


Ethernet 


Not used - May be cabled to HABIT 


CN4 


Audio 


Cabled to HABIT 


CN5 


PCI 


Not used 


CN6 


CD Audio IN 


Not used 


CN7 


AUX Line In 


Not used 


CN8 


Main Power 


Cabled to HABIT 


CN9 


Keyboard & Mouse 


Not used — May be cabled to HABIT 


CNIO 


Floppy Drive 


Not used 


CNll 


PC/i04 ISA bus Expansion 


CARD STACK 


CN12 


IDE Hard Drive 


Not used 


CN13 


Reserved 


Not used 


CN14 


Parallel Port 


Cabled to HABIT 


CN15 


Front Panel 


Not used 
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N.2-PCM-3810RAMConfiguration N-3 



CN16 


USB 


Not used - May be cabled to HABIT 


CN17 


IR 


Not used 


CN18 


CRT Display 


Cabled to HABIT 


CN19 


Video Out 


Not used 


CN20 


Flat Panel 


Not used 


CN21 


Ext. Flat Panel 


Not used 


CN22 


Peripheral Power 


Not used 


CN23 


COM Ports 


Cabled to HABIT 


CN30 


Video In 


Not used 


CN501 


Compact Flash 


Not used 


CN502 


Speaker Out 


Not used 


DIMl 


DIMM 


Dynamic Ram 


Jl 


ATX Feature 


Not used 


JP3 


LVDS 


Not used 



2. PCM-3810 RAM CONFIGURATION 



A. Flow/Block Diagram 

Not available from Shuffle Master, please contact Advantec, 

B. Schematic Diagram 
Attached 

C. Layout Diagram 

Please refer to page 1 of the PCM-3810A PC/104 Solid-State Disk Module manual, avail- 
able from Advantec. 

D. Parts List 

Not available from Shuffle Master, please contact Advantec. 

E. Jumper Settings 

Strapping for the "PCM-3810A PC/104 Solid State Disk Module." Battery backed Static 
RAM configuration. 



Jl 2 =^ 
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N.3 - PCM-3810OS/DOCConfiguration 



N-4 





2 


2 




Module Address D800 




J3 


2 


2 








J4 


2 


2 


2 


B2S3 - Disk On Chip Disabled 




J5 


2 


2 


2 


B2S3 - Battery Enabled 




J6 


2 


2 


2 


Bl - Battery Disabled 




J7 


2 


2 


2 


B2 - Battery Enabled 






B 
S< 


ank I 
3cket 3 




Static RAM 




Bank 1 
Socket 2 




Static RAM 




Bank 1 
Socket 1 




Static RAM 



J8 2 2 2 2 

Internal Batteries Connected 



R Removable Components 

Ml - Bank 1, Socket 1 - not currently used, 
M2 - Bank 1, Socket 2 - not currently used, 
M3 - Bank 1, Socket 3 ~ not currently used. 
M4 - Bank 2, Socket 1 - Static RAM 
M5 - Bank 2, Socket 2 - Static RAM 
M6 - Bank 2, Socket 3 - Static RAM 
BTl - Battery - Installed 
BT2 - Battery - Installed 

G. Connections 

PC/104 Connector - PC bus 
CNl - Reserved by Advantec. 

3. PCM-3810 OS/DOC Configuration 

A. Flow/Block Diagram 

Not available from Shuffle Master, please contact Advantec, 

B. Schematic Diagram 

Not available from Shuffle Master, please contact Advantec. 
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N.3 - PCM-3810 OS/DOC Configuration 



N-5 



C. Layout Diagram 

Please refer to page 1 of the PCM-3810A PC/104 Solid-State Disk Module manual, avail- 
able from Advantec. 

D. Parts List 

Not available from Shuffle Master, please contact Advantec. 

E. Jumper Settings 

Strapping for the "PCM-3810A PC/i04 Solid State Disk Module." Operating System and 
Disk on Chip configuration. 









JI 


2 2 


Module Address DCOO 


52 


2 2 




53 


2 2 




J4 


2 2 


= B2S3 - Disk On Chip Enabled 


J5 


2 2 


^ B2S3 - Battery Disabled 


J6 


2 2 


^ Bl - Battery Disabled 


J7 


2 2 


2 B2 - Battery Disabled 




Shuffle Master Gaming 
Operating System ROM 3 




Shuffle Master Gaming 
Operating System ROM 2 




Shuffle Master Gaming 
Operating System ROM 1 



Disk On Chip 



Bank 2 
Socket 2 



Shuffle Master Gaming 
Operating System ROM 4 



J8 2 2 2 2 



Batteries Disconnected (Remove batteries from module) 



R Removable Components 

Bank 1, Socket 1 - SODS ROM # 1 
Bank 1 , Socket 2 SGOS ROM # 2 
Bank 1, Socket 3 - SGOS ROM # 3 
Bank 2, Socket 1 - SGOS ROM # 4 
Bank 2, Socket 2 - not currently used. 

Bank 2, Socket 3 - Disk On Chip - Game personality program. 
Batteries - Removed 
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N.4-HIC 



N-6 



G. Connections 

PC/104 Connector - PC bus 
CNl — Reserved by Advantec, 

4. HIC 

A. Flow/Block Diagram 
Attached "HICflow.vsd" 

B. Schematic Diagram 
Attached 

C. Layout Diagram 
Attached 

D. Parts List 
Attached 

E. Jumper Settings 

One jumper that selects SRAM secondary enable from either Vcc or Battery Monitor. Cur- 
rently the jumper is set to select Vcc by shorting pins 1-2, pin 3 is open. (Jumper away 
from the connector.) 

F. Removable Components 

U2 - Control Decode GAL 
U3 — Address Decode GAL 
UIO- Watchdog ROM 

G. Connections 

JPl, JP2 - PC/104 Connector - PC bus 
PI -I/O to HABIT 

5. HABIT 

A. Flow/Bloci( Diagram 

Attached "HABITflow.vsd" 

Sciiematic Diagram 

Attached 
C. Layout Diagram 

Attached 
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N.&-HABIT 



D. Parts List 

Attached 

E. Jumper Settings 

No jumpers, however there is an ECO to remove the non-v^orking power off door monitor 
circuit. 

See Engineering Change Orders FTC-001, FTC-002, and FTC-003, available from 
Advantec. 

F. Removable Components 

There are no removable components. 

G. Connections 

PI ~ Game Harness 
P2 — Game Harness 

Jl - Feed through COMM ports from CHIMP 

J4 — from Power Supply 

J8 - Audio from CHIMP 

J9 - Feed through Printer from CHIMP 

JIO - Feed through USB from CHIMP 

Jll - Feed through Keyboard & Mouse from CHIMP 

J12 — Feed through Ethernet from Chimp 

J13 - Feed through Video from CHIMP 

J14 - Power for CHIMP 

J16- I/O from HIC 
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Appendix O — Further Help and 
Troubleshooting 

1 . Shuffle Master Website 

shufflemastersupport.com 

2. Troubleshooting 

[add list of known problems and solutions] 
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What is Claimed is: 

1 . A method of assisting in the development of a computer based wagering 
gaming application comprising: 

5 providing a gaming operating system comprising a library of at least two 

software gaming callback functions and/or primary gaming states; 

providing an Application Programming Interface enabling communication 
from a distal intelligence source to the gaming operating system; 

communicating with the Application Programming Interface to the functions 
10 and/or primary gaming states in the library of the gaming operating system by 

providing a Makefile or other procedure for building a gaming application, and a 
configuration file for running the gaming operation system on a proximal computing 
system; 

providing gaming specific data relating to at least one specific gaming 
15 application; and 

compiling a program specific to at least one gaming application that is 
compatible with the gaming operating system. 

2. The method of assisting in the development of a computer based wagering 
20 gaming application according to claim 1 comprising the steps of: 

wherein the library of at least two software gaming elements comprises 
gaming elements selected from the group consisting of random number generator, 
game initiation sequence, bonus module, video gaming module, audio gaming 
module, jackpot module, graphics conversion tool, debugging tool, pay-out table 
25 module, value-handling module, power-loss recovery module, gaming payout history 

module, player history module, and user interaction module. 

3. The method of claim 2 wherein public and/or private authentication keys 
are revved and different public and/or private authentication keys is provided to each 

30 of at least two different legal jurisdictions. 
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4. The method of claim 1 wherein the computerized wagering game 
application is developed for an apparatus comprising: 

a computerized game controller operable to control the computerized 
wagering game having a processor, memory, and nonvolatile storage; and 

an operating system comprising: a system handler application which 
provides gaming related functions and services to game programs; and 

an operating system kernel that executes the system handler 

application. 

5. The method of claim 4 wherein the system handler application comprises at 
least one system selected from the group consisting of 

a) a plurality of device handlers, 

b) software having the ability when executed to: 

load a gaming program; and 
execute the new gaming program; 

c) an API with functions callable from the game program; 

d) an event queue; 

e) a game personality described in a selected mode; and 

f) a combination of an event queue that determines the order of execution of 
each specified device handler; an API having a library of functions; an event 
queue capable of queuing on a first come, first serve basis; and an event queue 
capable of queuing using more than one criteria. 

6. The method of claim 4 wherein game data modified by gaming 
program objects is stored in nonvolatile storage or wherein the system handler and 
kernel work in communication to hash system handler code and operating system 
kernel code. 
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7. The method of claim 6, wherein game data modified by gaming 
program objects is stored in nonvolatile storage and changing game data in 
nonvolatile storage causes execution of a corresponding callback function in the 
system handler application. 

5 

8. The method of claim 4, wherein the operating system kernel is a Linux 
operating system kernel having customized proprietary modules and the kernel has at 
least one modification wherein each modification is selected from the group 
consisting of: 1) accessing user level code from ROM, 2) executing from ROM, 3) 

10 zero out unused RAM, 4) test and/or hash the kernel, and 5) disabling selected device 

handlers. 



9. The method of claim 4 wherein the apparatus contains a machine-readable 
element with machine-readable instructions thereon, the instructions when executed 
15 operable to cause the processor to manage at least one gaming program object via a 

system handler application and to execute a single gaming program object at any one 
time, wherein gaming program objects are operable to share game data in nonvolatile 
storage within the processor in the computerized wagering game system. 

20 1 0. The method of claim 9 wherein programming directs the gaming 

apparatus to effect a procedure selected fi-om the group consisting of a) only one 
gaming program object executes at any one time, b) there are instructions operable 
when executed to cause a computer to provide functions through an API that 
comprises a part of the system handler application, and c) when instructions are 

25 executed, the instructions are operable to store game data in nonvolatile storage, such 

that the state of the computerized wagering game system is maintained when the 
machine loses power. 
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11. A method wherein after compiling a program specific to at least one 
gaming application that is compatible with the gaming operating system according to 
claims 1, 2, 3, 4 or 5, the program specific to at least one gaming application of 
manages data in the computerized wagering game apparatus via a system handler 
5 application comprising: 

loading a shared object, 

executing the shared object, and 

accessing and storing game data in nonvolatile storage. 

10 12. The method of claim 1 1 wherein managing data further comprises a) 

unloading the first program object, and loading a second program object or b) 
executing a corresponding callback function upon alteration of game data in 
nonvolatile storage. 

15 13. The method of claim 1 wherein after compiling a program specific to 

at least one gaming application that is compatible with the gaming operating system, a 
machine-readable memory storage element with instructions thereon has the 
instructions executed to cause a computer to: 

load a first program shared object, 
20 execute a first progi'am shared object, 

store gaming data in nonvolatile storage, such that a second program 
object later loaded can access gaming data variables in nonvolatile storage, 

unload the first program shared object from system memory, and 
load the second program shared object to system memory so that the 
25 second program shared object is accessible to the computer as instructions. 

14. The method of claim 13 wherein additional instructions are executed to 
cause a computer to perform a task selected from the group consisting of a) executing 
a corresponding callback function upon alteration of game data in the nonvolatile 
30 storage; and b) managing events via the system handler application. 
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15. The method of claim 1 wherein the computerized wagering game 
application is developed for an apparatus comprising: 

a universal operating system stored in a memory storage component that may 
be operatively inserted along with game identity data into an electronic or 
5 electromechanical gaming device having ancillary functions so that the gaming device 

can effect play of the game provided in the game identity data and the operating 
system will control at least one ancillary function selected from the gi'oup consisting 
of coin acceptance, credit acceptance, currency acceptance and boot up, the gaming 
device having at least one system handler application, and the operating system 
10 comprising a system handler and an operating system kernel. 

16. The method of claim 15 wherein the apparatus further comprises at least 
one of a plurality of APIs, an operating system kernel customized for gaming 
purposes, and an event queue. 

15 

17. The method of claim 15 wherein the apparatus further comprises a 
system handler comprising a plurality of device handlers or the operating system 
controls a networked on-line system or control a progressive meter. 

20 18. The method of claim 1 5 wherein the operating system comprises a 

kernel customized for gaming purposes utilizing a method of operation selected from 
the group consisting of: 1) accessing user level code from ROM, 2) executing from 
ROM, 3) zero out unused RAM, 4) test and/or hash tlie kernel, and 5) disabling 
selected device handlers. 
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19. A method comprising a) customizing an operating system kernel and 
b) providing the customized kernel of the operating system into a gaming apparatus, 
at least one customization being effected to obtain functionality of the gaming 
apparatus, the customization being a kernel modification for a process selected from 

5 the group consisting of: 

1) accessing user level code from ROM; 

2) executing user level code from ROM; 

3) zeroing out unused RAM; 

4) testing and/or hashing the kernel; and 
10 5) disabling selected device handlers. 

20. A method of converting a first game that operates on a first gaming 
system so that the game operates on a universal gaming system, the method 
comprising: 

15 removing a first game operating system from the gaming system, the 

first game operating system including hardware and software; 

installing the universal gaming system of claim 15 in place of the game 
operating system, the universal gaming system including a game program layer, an 
open operatmg system, and a game controller for running the game program layer on 
20 the open operating system; 

providing fimctional interfaces between the universal gaming system 
and game devices; and 

installing a second game specific program in the game program layer 
configured to operate with the open operating system. 

25 

2 1 . The method of claim 20, comprising at least one step selected from the 
group consisting of: 

a) providing the open operating system with a system application 
handler, wherein the fimctional interfaces include a functional interface between the 
30 gaming system and the game devices via the system application handler; 
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b) configuring the system handler application to include one or more 
device handlers for interfacing with the game devices, v^herein at least one of the 
device handlers operates as a protocol manager between the games device and the 
open operating system; 

5 c) providing the open operating system to include an operating system 

kernel that executes the system handler application; and 

d) providing the game program layer with at least one gaming program 

object. 

10 22. The method of claim 2 1 , wherein the at least one gaming program 

object is specific to a type of game played on the universal gaming system. 

23. The method of claim 20, comprising at least one step selected from the 
group consisting of : 

1 5 changing a type of game played on the u^niversal gaming system by 

changing game program objects; 

configuring the game program layer to operate the game as a slot 

machine; 

operating the slot machine as a mechanical reel-based slot machine; 

20 and 

configuring the open operating system to include a resource manager 
for mapping game specific resources. 

24. The method of claim 23 including mapping game specific resources by 
25 parsing a configuration file, mapping operating system resources based on the 

configuration file, and storing the resource map in memory. 

25. The method of claim 24, wherein mapping operating system resources 
based on the configuration file includes mapping input/output lines to system 

30 resources. 
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26. The method of clahn 22 comprising converting the first gaming system 
from a cash accepting gaming system to a cashless gaming system, the method 
including providing the open operating system with a system application handler, 
wherein the functional interfaces include a functional interface between the gaming 

5 system and the game devices accomplished via the system application handler, and 

configuring the system handler application to include one or more device handlers for 
interfacing with the game devices, the configuring including installing a card reader 
device handler, and installing a card reader in communication with the card reader 
device handler, and optionally including configuring the system handler application to 

10 include a ticket printer device handler; and installing a ticket printer in 

communication with the ticket printer device handler. 

27. The method of claim 22 wherein a slot machine game operating system 
is removed from the first gaming system and the functional interfaces are between the 

15 universal gaming system and slot machine game devices. 

28. The method of claim 27 comprising at least one step selected from the 
group consisting of: 

a) providing the open operating system with a system application handler, 
20 wherein the functional interfaces include a functional interface between the gaming 

system and the slot machine game devices via the system application handler; 

b) configuring the system handler application to include one or more device 
handlers for interfacing with the slot machine game devices, wherein at least one of 
the device handlers operates as a protocol manager between the slot machine games 

25 device and the open operating system; 

c) configuring an I/O device handler to interface with slot machine input 
devices and slot machine output devices; 

d) providing slot machine input devices that include a mechanical arm, button 
acceptor and coin acceptor; 

30 e) providing the slot machine with output devices inclusive of slot machine 

reels, credit displays, and speakers. 
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29. The method of claim 28, comprising converting the mechanical reel 
slot machine game having only cash, token, credit balance and currency acceptance 
capability to a cashless gaming system via the system handler application, the 
5 converting including providing a card reader device handler, and installing a card 

reader in communication with the card reader device handler and optionally providing 
a ticket printer device handler, and installing a ticket printer in communication with 
the ticket printer device handler. 

10 30. A method of configuring a game program layer for a universal gaming 

system that is configured for a game program layer and an open operating system, the 
method comprising: 

configuring the game program layer on a computer remote from a first 
non-universal gaming system; and 
15 downloading the game program layer into the universal gaming system 

and performing at least one sequence comprising 

a) defining a game template; and configuring the game program 
layer using the game template; 

b) storing the game program on a removable media card; 
20 c) providing removable media as flash memory. 

3 1 . The method of claim 30 wherein the game program is stored on a 
removable media card and the removable media card is plugged into the gaming 
system, and then running the game program layer via the open operating system from 

25 the removable media card. 

32. The method of claim 30 comprising an additional step of preparing the 
game program layer for authentication by plugging the removable media card into an 
authenticating system. 

30 
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10 



33. The method of claim 30 performed as a network based method of 
providing a game program layer for a universal gaming system configured for remote 
operation using an open operating system, the method including defining a user 
interface to communicate between the remote computer and the universal operating 
system. 

34. The method of claim 33 wherein the game program layer is configured to 
use user interface remote from the gaming system or via a web page template at the 
user interface. 



35. A gaming system developed for use in a casino by the method of claim 
1 comprising: 

a game controller configured to operate the gaming system; and 
a first nonvolatile memory and a second nonvolatile memory for 
15 storing critical gaming information, wherein the first nonvolatile memory and the 

second nonvolatile memory are configured to communicate with the game controller 
as a gaming RAID system for redundant storage of critical gaming information. RAID 
not defined in text, 

the gaming system enabling redundant NVRAM storage to be replaceable 
20 while operating power for the system is on. 
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